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

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 15 Jul 2021 17:44:22 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
>  asjo@koldfront.dk, emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> 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 think having some examples is fine in doc strings -- it can be
> difficult to explain some concepts in words, but a simple example can be
> a really efficient way to say what a function does.
> 
> But we should indeed not go overboard with examples in doc strings --
> that's better left for the manual.

The danger of going overboard is exactly what bothers me.  Which is
why I think examples in doc strings should be used in exceptional
cases, where they are absolutely necessary.  Not as a "why not?"
addition.