GNU bug report logs - #22462
25.0.50; Docstring of cl-defun/defmacro are too short

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 22462 in the body.
You can then email your comments to 22462 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: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Mon, 25 Jan 2016 08:43:13 +0000

Every time I turn to cl-defun or cl-defmacro (usually for the extra
arglist versatility), I end up asking myself “was it &key or &keys?” or
“what was the name of that really long option?”.

Naturally, I turn to `C-h f cl-defun', only to be told that it works
“Like normal ‘defun’, except ARGLIST allows full Common Lisp
conventions”. That's not very helpful for someone who's not profficient
in Common Lisp.

I think there should be a link to the relevant info node and, preferably,
a brief summary of the conventions.

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

From: Marcin Borkowski <mbork <at> mbork.pl>
To: Artur Malabarba <bruce.connor.am <at> gmail.com>
Cc: 22462 <at> debbugs.gnu.org
Subject: Re: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Mon, 25 Jan 2016 12:04:04 +0100

On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am <at> gmail.com> wrote:

> Every time I turn to cl-defun or cl-defmacro (usually for the extra
> arglist versatility), I end up asking myself “was it &key or &keys?” or
> “what was the name of that really long option?”.
>
> Naturally, I turn to `C-h f cl-defun', only to be told that it works
> “Like normal ‘defun’, except ARGLIST allows full Common Lisp
> conventions”. That's not very helpful for someone who's not profficient
> in Common Lisp.
>
> I think there should be a link to the relevant info node and, preferably,
> a brief summary of the conventions.

+1.  And I'd vote for a summary, not a link.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Marcin Borkowski <mbork <at> mbork.pl>, Artur Malabarba
 <bruce.connor.am <at> gmail.com>
Cc: 22462 <at> debbugs.gnu.org
Subject: RE: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Mon, 25 Jan 2016 06:23:24 -0800 (PST)

+1. The Emacs Common-Lisp emulations have generally just punted
wrt doc, sending you off to consult the C-L doc.  That's OK
for a start, but it could be better.  Especially, any differences
from the C-L behavior should be noted (they usually are).

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Artur Malabarba <bruce.connor.am <at> gmail.com>
Cc: 22462 <at> debbugs.gnu.org
Subject: Re: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Mon, 25 Jan 2016 17:58:54 +0200

> From: Artur Malabarba <bruce.connor.am <at> gmail.com>
> Date: Mon, 25 Jan 2016 08:43:13 +0000
> 
> I think there should be a link to the relevant info node and, preferably,
> a brief summary of the conventions.

A link to the manual shouldn't replace the documentation in the doc
string.  It could explain more and provide additional background
information, but the essentials should be in the doc string.

I hope Someone™ will volunteer soon to fill the voids.  TIA.

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

From: npostavs <at> users.sourceforge.net
To: Marcin Borkowski <mbork <at> mbork.pl>
Cc: Artur Malabarba <bruce.connor.am <at> gmail.com>, 22462 <at> debbugs.gnu.org
Subject: Re: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Sat, 02 Jul 2016 00:02:46 -0400

[Message part 1 (text/plain, inline)]

tags 22462 patch
quit

Marcin Borkowski <mbork <at> mbork.pl> writes:

> On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am <at> gmail.com> wrote:
>
>> Every time I turn to cl-defun or cl-defmacro (usually for the extra
>> arglist versatility), I end up asking myself “was it &key or &keys?” or
>> “what was the name of that really long option?”.
>>
>> Naturally, I turn to `C-h f cl-defun', only to be told that it works
>> “Like normal ‘defun’, except ARGLIST allows full Common Lisp
>> conventions”. That's not very helpful for someone who's not profficient
>> in Common Lisp.
>>
>> I think there should be a link to the relevant info node and, preferably,
>> a brief summary of the conventions.
>
> +1.  And I'd vote for a summary, not a link.

Here's a patch adding both a terse summary and a link, does it look ok?

[v1-0001-Add-details-to-cl-lib-defining-macros-docstrings.patch (text/x-diff, inline)]

From a19d4e880eb54cd68733666cdb43f4c7510ad91b Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs <at> gmail.com>
Date: Fri, 1 Jul 2016 23:53:26 -0400
Subject: [PATCH v1] Add details to cl-lib defining macros docstrings

* lisp/emacs-lisp/cl-macs.el (cl-defun, cl-defmacro): Add terse summary
of supported arglist forms (Bug #22462).
---
 lisp/emacs-lisp/cl-macs.el | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 2cb821e..c51ed9d 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -327,6 +327,20 @@ cl-defun
 Like normal `defun', except ARGLIST allows full Common Lisp conventions,
 and BODY is implicitly surrounded by (cl-block NAME ...).
 
+The full form of a Common Lisp function argument list is
+
+   (VAR...
+    [&optional (VAR [INITFORM [SVAR]])...]
+    [&rest|&body VAR]
+    [&key (([KEYWORD] VAR) [INITFORM [SVAR]])... [&allow-other-keys]]
+    [&aux (VAR [INITFORM])...])
+
+VAR maybe be replaced recursively with an argument list for
+destructing, `&whole' is supported within these sublists.  If
+SVAR, INITFORM, and KEYWORD are all omitted, then `(VAR)' may be
+written simply `VAR'.  See the Info node `(cl)Argument Lists' for
+more details.
+
 \(fn NAME ARGLIST [DOCSTRING] BODY...)"
   (declare (debug
             ;; Same as defun but use cl-lambda-list.
@@ -406,6 +420,21 @@ cl-defmacro
 Like normal `defmacro', except ARGLIST allows full Common Lisp conventions,
 and BODY is implicitly surrounded by (cl-block NAME ...).
 
+The full form of a Common Lisp macro argument list is
+
+   (VAR...
+    [&optional (VAR [INITFORM [SVAR]])...]
+    [&rest|&body VAR]
+    [&key (([KEYWORD] VAR) [INITFORM [SVAR]])... [&allow-other-keys]]
+    [&aux (VAR [INITFORM])...]
+    [&environment VAR])
+
+VAR maybe be replaced recursively with an argument list for
+destructing, `&whole' is supported within these sublists.  If
+SVAR, INITFORM, and KEYWORD are all omitted, then `(VAR)' may be
+written simply `VAR'.  See the Info node `(cl)Argument Lists' for
+more details.
+
 \(fn NAME ARGLIST [DOCSTRING] BODY...)"
   (declare (debug
             (&define name cl-macro-list cl-declarations-or-string def-body))
-- 
2.8.0

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

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: npostavs <at> users.sourceforge.net, Marcin Borkowski <mbork <at> mbork.pl>
Cc: 22462 <at> debbugs.gnu.org
Subject: Re: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Tue, 05 Jul 2016 23:06:40 +0000

[Message part 1 (text/plain, inline)]

Looks fine to me!

On Sat, Jul 2, 2016 at 1:02 AM <npostavs <at> users.sourceforge.net> wrote:

> tags 22462 patch
> quit
>
> Marcin Borkowski <mbork <at> mbork.pl> writes:
>
> > On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am <at> gmail.com>
> wrote:
> >
> >> Every time I turn to cl-defun or cl-defmacro (usually for the extra
> >> arglist versatility), I end up asking myself “was it &key or &keys?” or
> >> “what was the name of that really long option?”.
> >>
> >> Naturally, I turn to `C-h f cl-defun', only to be told that it works
> >> “Like normal ‘defun’, except ARGLIST allows full Common Lisp
> >> conventions”. That's not very helpful for someone who's not profficient
> >> in Common Lisp.
> >>
> >> I think there should be a link to the relevant info node and,
> preferably,
> >> a brief summary of the conventions.
> >
> > +1.  And I'd vote for a summary, not a link.
>
> Here's a patch adding both a terse summary and a link, does it look ok?
>
>

[Message part 2 (text/html, inline)]

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

From: npostavs <at> users.sourceforge.net
To: Artur Malabarba <bruce.connor.am <at> gmail.com>
Cc: Marcin Borkowski <mbork <at> mbork.pl>, 22462 <at> debbugs.gnu.org
Subject: Re: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Sat, 09 Jul 2016 11:01:03 -0400

tags 22462 fixed
close 22462 25.1
quit

Artur Malabarba <bruce.connor.am <at> gmail.com> writes:

> Looks fine to me!
>

Pushed as aac62a67

Previous Next

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