GNU bug report logs - #9259
extra line in "unless" docstring?

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9259 in the body.
You can then email your comments to 9259 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: jidanni <at> jidanni.org
To: bug-gnu-emacs <at> gnu.org
Subject: extra line in "unless" docstring?
Date: Mon, 08 Aug 2011 11:13:06 +0800

unless is a Lisp macro in `subr.el'.

(unless COND BODY...)

If COND yields nil, do BODY, else return nil. <--------what is this line doing here?
When COND yields nil, eval BODY forms sequentially and return
value of last one, or nil if there are none.

Message #10 received at 9259-done <at> debbugs.gnu.org (full text, mbox):

From: Juanma Barranquero <lekktu <at> gmail.com>
To: jidanni <at> jidanni.org
Cc: 9259-done <at> debbugs.gnu.org
Subject: Re: bug#9259: extra line in "unless" docstring?
Date: Mon, 8 Aug 2011 15:51:15 +0200

> (unless COND BODY...)
>
> If COND yields nil, do BODY, else return nil. <--------what is this line doing here?

The same happens for `when', BTW.

It's not a bug. Most docstrings are written so the first line provides
a summary of the corresponding function/macro/special form/variable.
This makes the output of apropos more useful.

    Juanma

Message #13 received at 9259 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: jidanni <at> jidanni.org
Cc: 9259 <at> debbugs.gnu.org
Subject: Re: bug#9259: extra line in "unless" docstring?
Date: Sat, 20 Aug 2011 17:48:32 -0400

jidanni <at> jidanni.org writes:

> unless is a Lisp macro in `subr.el'.
>
> (unless COND BODY...)
>
> If COND yields nil, do BODY, else return nil. <--------what is this
> line doing here?
> When COND yields nil, eval BODY forms sequentially and return
> value of last one, or nil if there are none.

It's the one-line summary of the function.  Every docstring has one.

Message #16 received at 9259 <at> debbugs.gnu.org (full text, mbox):

From: jidanni <at> jidanni.org
To: cyd <at> stupidchicken.com
Cc: 9259 <at> debbugs.gnu.org
Subject: Re: bug#9259: extra line in "unless" docstring?
Date: Sun, 21 Aug 2011 06:15:14 +0800

>>>>> "CY" == Chong Yidong <cyd <at> stupidchicken.com> writes:
CY> jidanni <at> jidanni.org writes:

>> unless is a Lisp macro in `subr.el'.
>> 
>> (unless COND BODY...)
>> 
>> If COND yields nil, do BODY, else return nil. <--------what is this
>> line doing here?
>> When COND yields nil, eval BODY forms sequentially and return
>> value of last one, or nil if there are none.

CY> It's the one-line summary of the function.  Every docstring has one.

Well e.g., man pages have headers "SUMMARY" etc. separating the different
parts. If the rendering jammed them all together it would look bad.

Even in debian apt there is indentation:

Description: Web browser based on Firefox
 Iceweasel is Firefox, rebranded. It is a powerful, extensible web browser with
 support for modern web application technologies.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.