bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[Artur Malabarba]

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.

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[Marcin Borkowski]

On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am@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

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[Drew Adams]

+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).

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[npostavs]

[-- Attachment #1: Type: text/plain, Size: 858 bytes --]

tags 22462 patch
quit

Marcin Borkowski <mbork@mbork.pl> writes:

> On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am@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?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 2258 bytes --]

From a19d4e880eb54cd68733666cdb43f4c7510ad91b Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@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

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[Artur Malabarba]

[-- Attachment #1: Type: text/plain, Size: 1004 bytes --]

Looks fine to me!

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

> tags 22462 patch
> quit
>
> Marcin Borkowski <mbork@mbork.pl> writes:
>
> > On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am@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?
>
>

[-- Attachment #2: Type: text/html, Size: 1531 bytes --]

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[npostavs]

tags 22462 fixed
close 22462 25.1
quit

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

> Looks fine to me!
>

Pushed as aac62a67

bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short

[Eli Zaretskii]

> From: Artur Malabarba <bruce.connor.am@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.