* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short @ 2016-01-25 8:43 Artur Malabarba 2016-01-25 11:04 ` Marcin Borkowski 2016-01-25 15:58 ` Eli Zaretskii 0 siblings, 2 replies; 7+ messages in thread From: Artur Malabarba @ 2016-01-25 8:43 UTC (permalink / raw) To: 22462 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 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 2016-01-25 15:58 ` Eli Zaretskii 1 sibling, 2 replies; 7+ messages in thread From: Marcin Borkowski @ 2016-01-25 11:04 UTC (permalink / raw) To: Artur Malabarba; +Cc: 22462 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 2016-01-25 11:04 ` Marcin Borkowski @ 2016-01-25 14:23 ` Drew Adams 2016-07-02 4:02 ` npostavs 1 sibling, 0 replies; 7+ messages in thread From: Drew Adams @ 2016-01-25 14:23 UTC (permalink / raw) To: Marcin Borkowski, Artur Malabarba; +Cc: 22462 +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). ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 2016-01-25 11:04 ` Marcin Borkowski 2016-01-25 14:23 ` Drew Adams @ 2016-07-02 4:02 ` npostavs 2016-07-05 23:06 ` Artur Malabarba 1 sibling, 1 reply; 7+ messages in thread From: npostavs @ 2016-07-02 4:02 UTC (permalink / raw) To: Marcin Borkowski; +Cc: Artur Malabarba, 22462 [-- 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 ^ permalink raw reply related [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 2016-07-02 4:02 ` npostavs @ 2016-07-05 23:06 ` Artur Malabarba 2016-07-09 15:01 ` npostavs 0 siblings, 1 reply; 7+ messages in thread From: Artur Malabarba @ 2016-07-05 23:06 UTC (permalink / raw) To: npostavs, Marcin Borkowski; +Cc: 22462 [-- 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 --] ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 2016-07-05 23:06 ` Artur Malabarba @ 2016-07-09 15:01 ` npostavs 0 siblings, 0 replies; 7+ messages in thread From: npostavs @ 2016-07-09 15:01 UTC (permalink / raw) To: Artur Malabarba; +Cc: Marcin Borkowski, 22462 tags 22462 fixed close 22462 25.1 quit Artur Malabarba <bruce.connor.am@gmail.com> writes: > Looks fine to me! > Pushed as aac62a67 ^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 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 15:58 ` Eli Zaretskii 1 sibling, 0 replies; 7+ messages in thread From: Eli Zaretskii @ 2016-01-25 15:58 UTC (permalink / raw) To: Artur Malabarba; +Cc: 22462 > 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2016-07-09 15:01 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 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 2016-07-05 23:06 ` Artur Malabarba 2016-07-09 15:01 ` npostavs 2016-01-25 15:58 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).