From: npostavs@users.sourceforge.net
To: Marcin Borkowski <mbork@mbork.pl>
Cc: Artur Malabarba <bruce.connor.am@gmail.com>, 22462@debbugs.gnu.org
Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short
Date: Sat, 02 Jul 2016 00:02:46 -0400 [thread overview]
Message-ID: <87a8i0hel5.fsf@users.sourceforge.net> (raw)
In-Reply-To: <8760yhdior.fsf@mbork.pl> (Marcin Borkowski's message of "Mon, 25 Jan 2016 12:04:04 +0100")
[-- 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
next prev parent reply other threads:[~2016-07-02 4:02 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-01-25 8:43 bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Artur Malabarba
2016-01-25 11:04 ` Marcin Borkowski
2016-01-25 14:23 ` Drew Adams
2016-07-02 4:02 ` npostavs [this message]
2016-07-05 23:06 ` Artur Malabarba
2016-07-09 15:01 ` npostavs
2016-01-25 15:58 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87a8i0hel5.fsf@users.sourceforge.net \
--to=npostavs@users.sourceforge.net \
--cc=22462@debbugs.gnu.org \
--cc=bruce.connor.am@gmail.com \
--cc=mbork@mbork.pl \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.