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

Previous Next

Full log

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

Previous Next

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