Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Tim Cross]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Thu, 15 Jul 2021 13:39:54 +0200
>> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>, 
>>      Emacs developers <emacs-devel@gnu.org>
>> 
>> In general, I think we should include more examples in our
>> documentation.  shortdoc.el is a step forward here, and it would be
>> even better if you could see those examples when you pull up the
>> docstring of a function.
>
> IMO, examples are for the manual, not for the doc strings.  If some
> parts of our manuals could benefit from more examples, patches for
> that would be welcome.

I tend to agree. The doc strings should be short and concise and link to
the manual for more detailed explanation and examples. Things like eldoc
and tooltips can become annoying or overly distracting if they have lots
of text.

I do understand how the doc strings for car and cdr can seem less
helpful, especially as they are somewhat recursive i.e. I don't know
what the function 'car' does - docstring tells me it returns the car of
a list, but I still don't know what car is. However, to really
understand car (or cdr), you really need a bit more
understanding of lists, cons cells etc. So having a somewhat terse doc
string which includes a link to the manual may be a good thing as it
will encourage the user to look at the manual and possibly get some of
the additional information (plus caar, caadr, cddr etc).

-- 
Tim Cross