Re: Documentation for car and cdr

[Luc Teirlinck]

Ken Manheimer wrote:

   language lawyers know what `car' does - you need to ask what clues
   will help someone who is lost enough to ask.

If that person did `C-h f car' because he did not know what a car was,
that is, because he does not know the very basics of Lisp, the clue
that will help him is that he should learn Lisp by studying a manual,
not by reading docstrings.

If the person doing `C-h f car' _does_ know Lisp, then the only likely
reason why he consulted the docstring of car is because it is unclear
to him what happens if the arg is not a cons cell.  So the docstring
should make three things clear:

1.  If the arg is nil, `car' returns nil.

2.  If the arg is neither nil nor a cons cell, an error is thrown.

3.  If you do not want an error in the above case, use car-safe.

Here is the docstring of car:

    Return the car of list.  If arg is nil, return nil.
    Error if arg is not nil and not a cons cell.  See also `car-safe'.

    See Info node `(elisp)Cons Cells' for a discussion of related basic
    Lisp concepts such as car, cdr, cons cell and list.

That last sentence was added by me (on Richard's request) yesterday in
a desperate, but apparently futile, attempt to make this time wasting
thread stop.

If the docstring of car does not make the three points above clear
enough, it needs fixing.  Otherwise it does not.

Sincerely,

Luc.