From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: npostavs@users.sourceforge.net Newsgroups: gmane.emacs.bugs Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Date: Sat, 02 Jul 2016 00:02:46 -0400 Message-ID: <87a8i0hel5.fsf@users.sourceforge.net> References: <87d1sqqcbi.fsf@gmail.com> <8760yhdior.fsf@mbork.pl> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: ger.gmane.org 1467432207 4385 80.91.229.3 (2 Jul 2016 04:03:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 2 Jul 2016 04:03:27 +0000 (UTC) Cc: Artur Malabarba , 22462@debbugs.gnu.org To: Marcin Borkowski Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jul 02 06:03:16 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bJC9D-0001fD-Dx for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Jul 2016 06:03:15 +0200 Original-Received: from localhost ([::1]:36836 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bJC9C-000884-9O for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Jul 2016 00:03:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57315) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bJC95-00086s-66 for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2016 00:03:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bJC90-0004hc-V5 for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2016 00:03:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:50199) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bJC90-0004hP-R9 for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2016 00:03:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bJC90-0007hU-I7 for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2016 00:03:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Jul 2016 04:03:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 22462 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.146743216729578 (code B ref 22462); Sat, 02 Jul 2016 04:03:02 +0000 Original-Received: (at 22462) by debbugs.gnu.org; 2 Jul 2016 04:02:47 +0000 Original-Received: from localhost ([127.0.0.1]:34303 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bJC8l-0007gu-FX for submit@debbugs.gnu.org; Sat, 02 Jul 2016 00:02:47 -0400 Original-Received: from mail-io0-f180.google.com ([209.85.223.180]:35018) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bJC8g-0007gZ-Vb; Sat, 02 Jul 2016 00:02:44 -0400 Original-Received: by mail-io0-f180.google.com with SMTP id f30so115327583ioj.2; Fri, 01 Jul 2016 21:02:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=+typsBtGAs1nSafJPZlxXlr7OtlYlHXisvdRyPOpAKw=; b=M/f8PlxGiZD0cvNk/CnQYozp9bF3qaIoxT85b0bxEG6NKCF7gMzZgDTwT4cl5eDszK Ha6xrhsWUhHEMz0RxThWfQy9PU3yWZN1OQO/SYH5gZpYw+FVtRzqZaYF/HV4NyuEcL4K JCUO7DqxKAN5qsmiHxl2301ssdGAuWhZ3a2cmPYRYfb+vmQPMbvVDLAAptIAZ94ZoBar SPnNQ6/tH/uPKXDorwzcmbJ3ycPnqlJf1m7e3ptB1bWQlYE9dtqnmLgAcsvrAVsEPcLq +iv22fTmlCjnCDI595HdAav2+RFmLN5bOrSgnz9kMyhy2bCWetfwnFpFG+k/IhFEs+JB K3tQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=+typsBtGAs1nSafJPZlxXlr7OtlYlHXisvdRyPOpAKw=; b=AR5VxCZlgbMD5CWUf9O1JKOhRgvc+DzNuNRQMfq9gA+/am0DI3jBDuIz7A4cn/GNVn igr+h7T4hF6UumUIhLSBSzzW9eVfhiTF92XVdlucnT5p8Qgqg9G8HpGSI6Z8UFz31axz +YSRCp1U+rIPvlUVzG5HAN6RMGDDKlxycehPQGb700nkyl8nCLWmTzixFSOk6z2MyRMj d/NAESl0LcIdAhVu6fTyeD9FrihcRuPuWYSVl3oIhz/EEq79MysB+GBS77EBpsaQ42LM wQe6QJcBuAgJbcmPXc0i0BuuoIpTpp0B9HWMslPk2c56n/kdgOCAu5/9mqfl8CvCGOdb s/5A== X-Gm-Message-State: ALyK8tLs2/lwiZfRxrCRViVZ9Hx7vTukoNx3Ast7nk3tTdmg+TNNtQ9agulNcUXLMiWUIA== X-Received: by 10.107.43.213 with SMTP id r204mr1165147ior.81.1467432157306; Fri, 01 Jul 2016 21:02:37 -0700 (PDT) Original-Received: from zony (206-188-64-44.cpe.distributel.net. [206.188.64.44]) by smtp.googlemail.com with ESMTPSA id a17sm2806502ioa.27.2016.07.01.21.02.36 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Jul 2016 21:02:36 -0700 (PDT) In-Reply-To: <8760yhdior.fsf@mbork.pl> (Marcin Borkowski's message of "Mon, 25 Jan 2016 12:04:04 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.93 (gnu/linux) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:120274 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable tags 22462 patch quit Marcin Borkowski writes: > On 2016-01-25, at 09:43, Artur Malabarba wrot= e: > >> Every time I turn to cl-defun or cl-defmacro (usually for the extra >> arglist versatility), I end up asking myself =E2=80=9Cwas it &key or &ke= ys?=E2=80=9D or >> =E2=80=9Cwhat was the name of that really long option?=E2=80=9D. >> >> Naturally, I turn to `C-h f cl-defun', only to be told that it works >> =E2=80=9CLike normal =E2=80=98defun=E2=80=99, except ARGLIST allows full= Common Lisp >> conventions=E2=80=9D. That's not very helpful for someone who's not prof= ficient >> 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? --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=v1-0001-Add-details-to-cl-lib-defining-macros-docstrings.patch Content-Description: patch >From a19d4e880eb54cd68733666cdb43f4c7510ad91b Mon Sep 17 00:00:00 2001 From: Noam Postavsky 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 --=-=-=--