From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Documentation for car and cdr Date: Thu, 26 Jan 2006 09:34:43 +0000 (GMT) Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Trace: sea.gmane.org 1138279872 2417 80.91.229.2 (26 Jan 2006 12:51:12 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 26 Jan 2006 12:51:12 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jan 26 13:51:08 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1F26aU-0002ev-KZ for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 13:50:54 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F26ON-0003l0-Pk for ged-emacs-devel@m.gmane.org; Thu, 26 Jan 2006 07:38:23 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1F25ka-0007Gg-8N for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:57:17 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1F25hk-0006yb-25 for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:57:14 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1F25T1-0004ej-Ed for emacs-devel@gnu.org; Thu, 26 Jan 2006 06:39:08 -0500 Original-Received: from [193.149.49.134] (helo=acm.acm) by monty-python.gnu.org with esmtp (Exim 4.52) id 1F25QT-0005RN-Lx; Thu, 26 Jan 2006 06:36:30 -0500 Original-Received: from localhost (root@localhost) by acm.acm (8.8.8/8.8.8) with SMTP id JAA00311; Thu, 26 Jan 2006 09:34:44 GMT X-Sender: root@acm.acm Original-To: Thien-Thi Nguyen In-Reply-To: X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:49575 Archived-At: Hi, Thi! On 25 Jan 2006, Thien-Thi Nguyen wrote: >Alan Mackenzie 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.