[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomer
From: |
Glenn Morris |
Subject: |
bug#9082: Add hints to documentation of car and cdr for (e)lisp newcomers |
Date: |
Thu, 14 Jul 2011 15:47:43 -0400 |
User-agent: |
Gnus (www.gnus.org), GNU Emacs (www.gnu.org/software/emacs/) |
>>> DEFUN ("cdr", Fcdr, Scdr, 1, 1, 0,
>>> ! doc: /* Return the cdr (rest) of LIST. If arg is nil, return nil.
[...]
> ¹ "When cons cells are used to implement singly linked lists (rather
> than trees and other more complicated structures), the car operation
> returns the first element of the list, while cdr returns the rest of
> the list." - http://en.wikipedia.org/wiki/CAR_and_CDR
To me, "rest" means nothing with no context.
It's fine to say: "A returns the first element, and B the rest."
But just saying on its own "B returns the rest" with no reference to A
means nothing.
I might say "B returns everything but the first element".
But really, one should read the Lisp intro or something if one does not
know what car and cdr mean. The doc string of such fundamental functions
shouldn't be expected to bootstrap from zero knowledge IMO.
Oh, I see there is already a reference to the lisp manual in these doc
strings. So personally I don't think any change was needed...
Also to complete my bitching, this should be marked "tiny change" since
we don't have an Emacs assignment (only a Gnus one).