[Top][All Lists]
[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.
- Re: Documentation for car and cdr, (continued)
- Re: Documentation for car and cdr, Miles Bader, 2006/01/25
- Re: Documentation for car and cdr, Lennart Borgman, 2006/01/25
- Re: Documentation for car and cdr, Alfred M\. Szmidt, 2006/01/25
- Re: Documentation for car and cdr, Thien-Thi Nguyen, 2006/01/25
- Re: Documentation for car and cdr, Alan Mackenzie, 2006/01/25
- Re: Documentation for car and cdr, Karl Chen, 2006/01/25
- Re: Documentation for car and cdr, Luc Teirlinck, 2006/01/25
- Re: Documentation for car and cdr, Eli Zaretskii, 2006/01/25
- Re: Documentation for car and cdr, Miles Bader, 2006/01/26
- Re: Documentation for car and cdr, Thien-Thi Nguyen, 2006/01/25
- Re: Documentation for car and cdr,
Alan Mackenzie <=
- Re: Documentation for car and cdr, Tomas Zerolo, 2006/01/26
- Re: Documentation for car and cdr, Thien-Thi Nguyen, 2006/01/26
- Re: Documentation for car and cdr, Luc Teirlinck, 2006/01/25
- Re: Documentation for car and cdr, Kim F. Storm, 2006/01/25
- Re: Documentation for car and cdr, Peter Whaite, 2006/01/25
- Re: Documentation for car and cdr, David Kastrup, 2006/01/25
- Re: Documentation for car and cdr, Mario Domenech Goulart, 2006/01/25
- Re: Documentation for car and cdr, Richard M. Stallman, 2006/01/26
- Re: Documentation for car and cdr, Luc Teirlinck, 2006/01/26
- Re: Documentation for car and cdr, Peter Whaite, 2006/01/26