[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: The doc-strings for car and cdr are insulting.
From: |
Chris Smith |
Subject: |
Re: The doc-strings for car and cdr are insulting. |
Date: |
29 Oct 2004 20:21:36 -0400 |
User-agent: |
Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 |
Kevin Rodgers <address@hidden> writes:
> Richard Stallman wrote:
> > How about something like the following, changing "LIST" to
> "CONS", and
> > using "lhs" and "rhs":
> >
> > "car is a built-in function.
> > (car CONS)
> >
> > Return the \"left hand side\" of CONS. If CONS is nil, return nil.
> > If CONS is a list, the car is its first element.
> > Error if arg is not nil and not a cons cell. See also `car-safe'."
> >
> > and
> >
> > "cdr is a built-in function.
> > (cdr CONS)
> >
> > Return the \"right hand side\" of CONS. If CONS is nil, return nil.
> > If CONS is a list, the cdr is the list without its first element.
> > Error if arg is not nil and not a cons cell. See also `cdr-safe'."
> >
> > These are good.
>
> They are awful. A cons cells does not have left and right sides any
> more than a list has left and right elements. A cons cell has car and
> cdr components, which are the first element and the remaining elements
> of a list.
>
> As Albert Einstein said: Things should be made as simple as possible,
> but no simpler.
>
> --
> Kevin Rodgers
Sir,
There is a subjective character to documentation. I have no problem
with either version. Possibly corresponding C code could be
inserted for pedantic purposes. That, too, would help.
Best,
Chris