emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation for car and cdr


From: Alan Mackenzie
Subject: Re: Documentation for car and cdr
Date: Thu, 26 Jan 2006 09:34:43 +0000 (GMT)

Hi, Thi!

On 25 Jan 2006, Thien-Thi Nguyen wrote:

>Alan Mackenzie <address@hidden> writes:

>> I think that "car returns the car" and "cdr returns the cdr" have
>> negative value - they irritate without enlightening.

>the irritation is not inherent in the text of a docstring, and neither
>is the process of enlightenment (if any).

I didn't suggest they were.  Merely that these doc-strings irritate, and
that they fail to enlighten.  If they didn't irritate, would so many
people have contributed to this thread?  ;-)

>> Again, I disagree.  A fledgling Elisp hacker is likely to spend time
>> reading through existing code.  She's likely to expect C-h f to tell
>> her what the mysterious functions do.

>how the fledgling hacker handles unfulfilled expectations is probably a
>nice thing for the fledgling hacker to hack, rather than the docstring.

>> The OP and I want clarity.  Most doc strings are rigorous, clear and
>> helpful at the same time.  Why can't those for car and cdr also be so?
 
>it can't be so when someone doesn't let it be so.

OK, here are my suggestions.  I think they they are both clear enough and
rigorous enough:

" car is a built-in function.
  (car CONS)

  Return the car of CONS.  If CONS is nil, return nil.
  The car of a list or a dotted pair is its first element.

  Error if CONS is not nil and not a cons cell.  See also `car-safe'."

and

" cdr is a built-in function.
  (cdr CONS)

  Return the cdr of CONS.  If CONS is nil, return nil.
  The cdr of a list is the list without its first element.  The cdr of a
  dotted pair (A . B) is the second element, B.

  Error if arg is not nil and not a cons cell.  See also `cdr-safe'."


>thi

-- 
Alan.






reply via email to

[Prev in Thread] Current Thread [Next in Thread]