From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: Artur Malabarba Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 25 Jan 2016 10:44:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 22462 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 22462@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.145371863012055 (code B ref -1); Mon, 25 Jan 2016 10:44:01 +0000 Received: (at submit) by debbugs.gnu.org; 25 Jan 2016 10:43:50 +0000 Received: from localhost ([127.0.0.1]:35490 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNecg-00038N-N8 for submit@debbugs.gnu.org; Mon, 25 Jan 2016 05:43:50 -0500 Received: from eggs.gnu.org ([208.118.235.92]:46485) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNece-000389-Vj for submit@debbugs.gnu.org; Mon, 25 Jan 2016 05:43:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNecY-0004rm-TQ for submit@debbugs.gnu.org; Mon, 25 Jan 2016 05:43:43 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=BAYES_40,FREEMAIL_FROM, T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:44927) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNecY-0004ri-QQ for submit@debbugs.gnu.org; Mon, 25 Jan 2016 05:43:42 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:37441) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNecX-0003O5-TW for bug-gnu-emacs@gnu.org; Mon, 25 Jan 2016 05:43:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNecU-0004r4-GO for bug-gnu-emacs@gnu.org; Mon, 25 Jan 2016 05:43:41 -0500 Received: from mail-qg0-x22f.google.com ([2607:f8b0:400d:c04::22f]:33472) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNecU-0004r0-CM for bug-gnu-emacs@gnu.org; Mon, 25 Jan 2016 05:43:38 -0500 Received: by mail-qg0-x22f.google.com with SMTP id b35so104731963qge.0 for ; Mon, 25 Jan 2016 02:43:37 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:subject:date:message-id:mime-version:content-type :content-transfer-encoding; bh=opJP1MalgA6GVGlU4xaLLeuuZ6TogFjB3XFxH0OkTaM=; b=TM4zzq68gqrcJqCMvXBcD1AFC6hB9QYtzIGZ+wp2WLxNTEIk9xdJziUeuI1sQKJSKs AC76L+GSaB8jNIqng1HOSwqB1i9/l6GAuzlsD/qGqU9bVjxUJ/D1cBXwS+ioxoVBFyyi LVnCKsX56Yt0OLSCB+OGqpFC1QSE18+tc2GmRzn1wr60F2lhqSw/z8gQZWt3ACvp8sK9 rxVLX5ocoju+xLVXWaT549xYEYDppGi2l08QhX5k0pZsGeCjN0PBqXWrIp7gtVc/iZTY V8qmxoa31HoN2hwuMzA/FVGt0Ygq8x3NrDuJEj/O0gibJEL9mn1e/Lb3+fCfS0CyRATU tILg== 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:subject:date:message-id :mime-version:content-type:content-transfer-encoding; bh=opJP1MalgA6GVGlU4xaLLeuuZ6TogFjB3XFxH0OkTaM=; b=C2tSg6FN6hM57F/Kd2GjNthew6V+2IHbSyrgXkMyHTD3+HGMyoxAd39UdmMqwgTqKs 0xV+I2J4yrbr4GmM5z+1/vJsi2My1xVh1rhr9BcaCuqK9Y6ynALryDxTQfqOQIU6Bg0P lmVFHqdM1tcKP1yGm5hhYJr0b++W3n3A+5QUVoFeAqfuMlCjQzGkCV1USTe9X8jPQYoB KI0qi6LxKF4+TL+Z3hMrA/nY1tPwpH2TZXp+z5nrzcveVM+K7cW/QuQ6Aae883W/DsX+ X8Wzklg2I01UuNOFuppib3i+9V4+3HM1v+3Vzs5fpkbsg3AwvRZ3xUU98RlWyrXgexYF Ekmg== X-Gm-Message-State: AG10YOSpfV+JvABlC6tbfK59U9nX//jC1kL1Rel0Lt6lXEsyVL865d5/A7VDVSLmCRKSug== X-Received: by 10.140.104.100 with SMTP id z91mr20191872qge.26.1453718617658; Mon, 25 Jan 2016 02:43:37 -0800 (PST) Received: from Gandalf-Linux.gmail.com ([201.37.162.188]) by smtp.gmail.com with ESMTPSA id r8sm8444258qha.47.2016.01.25.02.43.35 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 25 Jan 2016 02:43:37 -0800 (PST) From: Artur Malabarba Date: Mon, 25 Jan 2016 08:43:13 +0000 Message-ID: <87d1sqqcbi.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) 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 &keys?= =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 Co= mmon Lisp conventions=E2=80=9D. That's not very helpful for someone who's not proffic= ient in Common Lisp. I think there should be a link to the relevant info node and, preferably, a brief summary of the conventions. From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: Marcin Borkowski Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 25 Jan 2016 11:05:01 +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: To: Artur Malabarba Cc: 22462@debbugs.gnu.org Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.145371985613939 (code B ref 22462); Mon, 25 Jan 2016 11:05:01 +0000 Received: (at 22462) by debbugs.gnu.org; 25 Jan 2016 11:04:16 +0000 Received: from localhost ([127.0.0.1]:35499 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNewS-0003cl-DL for submit@debbugs.gnu.org; Mon, 25 Jan 2016 06:04:16 -0500 Received: from mail.mojserwer.eu ([195.110.48.8]:56197) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNewQ-0003cc-Ao for 22462@debbugs.gnu.org; Mon, 25 Jan 2016 06:04:14 -0500 Received: from localhost (localhost [127.0.0.1]) by mail.mojserwer.eu (Postfix) with ESMTP id 4C6488F201D; Mon, 25 Jan 2016 12:04:11 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mail.mojserwer.eu Received: from mail.mojserwer.eu ([127.0.0.1]) by localhost (mail.mojserwer.eu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id CZXQRVU3sK67; Mon, 25 Jan 2016 12:04:05 +0100 (CET) Received: from localhost (unknown [109.232.24.28]) by mail.mojserwer.eu (Postfix) with ESMTPSA id 2B45B8F201C; Mon, 25 Jan 2016 12:04:05 +0100 (CET) References: <87d1sqqcbi.fsf@gmail.com> User-agent: mu4e 0.9.13; emacs 25.1.50.1 From: Marcin Borkowski In-reply-to: <87d1sqqcbi.fsf@gmail.com> Date: Mon, 25 Jan 2016 12:04:04 +0100 Message-ID: <8760yhdior.fsf@mbork.pl> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On 2016-01-25, at 09:43, Artur Malabarba 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 From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 25 Jan 2016 14:24: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: To: Marcin Borkowski , Artur Malabarba Cc: 22462@debbugs.gnu.org Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.14537318166382 (code B ref 22462); Mon, 25 Jan 2016 14:24:02 +0000 Received: (at 22462) by debbugs.gnu.org; 25 Jan 2016 14:23:36 +0000 Received: from localhost ([127.0.0.1]:35575 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNi3M-0001es-J6 for submit@debbugs.gnu.org; Mon, 25 Jan 2016 09:23:36 -0500 Received: from aserp1040.oracle.com ([141.146.126.69]:34569) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNi3K-0001eZ-SS for 22462@debbugs.gnu.org; Mon, 25 Jan 2016 09:23:35 -0500 Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u0PENSvc009028 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 25 Jan 2016 14:23:28 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0021.oracle.com (8.13.8/8.13.8) with ESMTP id u0PENSxZ017629 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Mon, 25 Jan 2016 14:23:28 GMT Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by userv0121.oracle.com (8.13.8/8.13.8) with ESMTP id u0PENR8Q011220; Mon, 25 Jan 2016 14:23:27 GMT MIME-Version: 1.0 Message-ID: <31ea5f16-0e11-4669-abba-f9144434db5c@default> Date: Mon, 25 Jan 2016 06:23:24 -0800 (PST) From: Drew Adams References: <87d1sqqcbi.fsf@gmail.com> <8760yhdior.fsf@mbork.pl> In-Reply-To: <8760yhdior.fsf@mbork.pl> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) +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). From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 25 Jan 2016 15:59:01 +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: To: Artur Malabarba Cc: 22462@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.145373751916270 (code B ref 22462); Mon, 25 Jan 2016 15:59:01 +0000 Received: (at 22462) by debbugs.gnu.org; 25 Jan 2016 15:58:39 +0000 Received: from localhost ([127.0.0.1]:36372 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNjXL-0004EL-Bx for submit@debbugs.gnu.org; Mon, 25 Jan 2016 10:58:39 -0500 Received: from eggs.gnu.org ([208.118.235.92]:53296) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aNjXK-0004EA-3s for 22462@debbugs.gnu.org; Mon, 25 Jan 2016 10:58:38 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNjXB-0000in-LD for 22462@debbugs.gnu.org; Mon, 25 Jan 2016 10:58:32 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39654) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNjXB-0000ij-I6; Mon, 25 Jan 2016 10:58:29 -0500 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4736 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aNjXA-0000x8-Ri; Mon, 25 Jan 2016 10:58:29 -0500 Date: Mon, 25 Jan 2016 17:58:54 +0200 Message-Id: <83io2h3b29.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <87d1sqqcbi.fsf@gmail.com> (message from Artur Malabarba on Mon, 25 Jan 2016 08:43:13 +0000) References: <87d1sqqcbi.fsf@gmail.com> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Artur Malabarba > 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. From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short 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: To: Marcin Borkowski Cc: Artur Malabarba , 22462@debbugs.gnu.org Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.146743216729578 (code B ref 22462); Sat, 02 Jul 2016 04:03:02 +0000 Received: (at 22462) by debbugs.gnu.org; 2 Jul 2016 04:02:47 +0000 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 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 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) 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) From: npostavs@users.sourceforge.net References: <87d1sqqcbi.fsf@gmail.com> <8760yhdior.fsf@mbork.pl> Date: Sat, 02 Jul 2016 00:02:46 -0400 In-Reply-To: <8760yhdior.fsf@mbork.pl> (Marcin Borkowski's message of "Mon, 25 Jan 2016 12:04:04 +0100") Message-ID: <87a8i0hel5.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.93 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) --=-=-= 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 --=-=-=-- From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: Artur Malabarba Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 05 Jul 2016 23:07: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: patch To: npostavs@users.sourceforge.net, Marcin Borkowski Cc: 22462@debbugs.gnu.org Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.14677600179996 (code B ref 22462); Tue, 05 Jul 2016 23:07:02 +0000 Received: (at 22462) by debbugs.gnu.org; 5 Jul 2016 23:06:57 +0000 Received: from localhost ([127.0.0.1]:38704 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bKZQe-0002b9-Et for submit@debbugs.gnu.org; Tue, 05 Jul 2016 19:06:56 -0400 Received: from mail-vk0-f54.google.com ([209.85.213.54]:34506) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bKZQd-0002ax-Dy for 22462@debbugs.gnu.org; Tue, 05 Jul 2016 19:06:56 -0400 Received: by mail-vk0-f54.google.com with SMTP id t66so909453vka.1 for <22462@debbugs.gnu.org>; Tue, 05 Jul 2016 16:06:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=02SMwp21Q97FTw5V/biPccWqabbeVTahMqFBYtSAK2c=; b=GWKJpxQlbeoxSFqLQHSbddIeaAJaw76fV3+JNm82eXjQWfzbxzp0CQWOiHdPbC/Ir/ BLRJBjvAIv6dEl7hYH52NE5zpO99bDhnDpL2dMDI01RlKlRd9RAs+F7EoHSc/7WuGyrH biwK0IC593OlY9kuBi9XFmbIwUdMfU0qhorWS0niq3wsEMCIy7cokON7nmYhNoJHqXi4 fu4m75/nu1mC4zN8M88bgAT645PQNYFneTIckJP6dmOvDUsiAShiFNJORUtc94BjBYvs b1dbE1f8+hgb4+A3PW1TReKHNC/t/USyaiX9vdwi1TOPYyaJ3qSCuzknxzcMAzo9jjln y82Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=02SMwp21Q97FTw5V/biPccWqabbeVTahMqFBYtSAK2c=; b=aemuu6ckyNW8KucNcing6UpA3AomgH2CO1Y2PZqJfvbhr6bwf6xFTfVvamiwvIZGND BBWrAOZUeyQySv+StzuWWLVPwD4LH8qt1n+PayM9wHeWjA1RMUgS89mCHJZXajuso4tx k6k37OIQ6WBClbmdXlMcwoCU4rJG+59okMmHigzWzqHI+D14YeW1euxr8WhQgi+OnQUW a/gVKz4V0EBOJusbUmj2dqvbTzChHkEaiIiRWSCYSWlMQmfARg+2rP1bHgCKtRtV+RKl 9kT4xJUBBZPQYYVQeqTj2K1gT3BVzuvJefLO8VTFU8Kk8A5Q0MHe0wrP0OMOFWDabUbL Ny8w== X-Gm-Message-State: ALyK8tInxpguQNApePJY4pJ2VygF50tXrQGPCxzpaZBQ24QSQBYi7hL4LlJpj9/cKa0ZCBE43yV+ID2HXitPBQ== X-Received: by 10.31.129.203 with SMTP id c194mr7234062vkd.26.1467760010057; Tue, 05 Jul 2016 16:06:50 -0700 (PDT) MIME-Version: 1.0 References: <87d1sqqcbi.fsf@gmail.com> <8760yhdior.fsf@mbork.pl> <87a8i0hel5.fsf@users.sourceforge.net> In-Reply-To: <87a8i0hel5.fsf@users.sourceforge.net> From: Artur Malabarba Date: Tue, 05 Jul 2016 23:06:40 +0000 Message-ID: Content-Type: multipart/alternative; boundary=001a1145037e03e2760536eb8237 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) --001a1145037e03e2760536eb8237 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Looks fine to me! On Sat, Jul 2, 2016 at 1:02 AM wrote: > tags 22462 patch > quit > > Marcin Borkowski writes: > > > On 2016-01-25, at 09:43, Artur Malabarba > wrote: > > > >> 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 &= keys?=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 fu= ll Common Lisp > >> conventions=E2=80=9D. That's not very helpful for someone who's not pr= officient > >> 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? > > --001a1145037e03e2760536eb8237 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Looks fine to me!

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

Marcin Borkowski <mb= ork@mbork.pl> writes:

> On 2016-01-25, at 09:43, Artur Malabarba <bruce.connor.am@gmail.com> wro= te:
>
>> Every time I turn to cl-defun or cl-defmacro (usually for the extr= a
>> arglist versatility), I end up asking myself =E2=80=9Cwas it &= key or &keys?=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 allow= s full Common Lisp
>> conventions=E2=80=9D. That's not very helpful for someone who&= #39;s not profficient
>> in Common Lisp.
>>
>> I think there should be a link to the relevant info node and, pref= erably,
>> a brief summary of the conventions.
>
> +1.=C2=A0 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?=

--001a1145037e03e2760536eb8237-- From unknown Sat Sep 13 11:13:18 2025 X-Loop: help-debbugs@gnu.org Subject: bug#22462: 25.0.50; Docstring of cl-defun/defmacro are too short Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 09 Jul 2016 15:02:01 +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: patch To: Artur Malabarba Cc: Marcin Borkowski , 22462@debbugs.gnu.org Received: via spool by 22462-submit@debbugs.gnu.org id=B22462.146807647320084 (code B ref 22462); Sat, 09 Jul 2016 15:02:01 +0000 Received: (at 22462) by debbugs.gnu.org; 9 Jul 2016 15:01:13 +0000 Received: from localhost ([127.0.0.1]:44280 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bLtkn-0005Dn-7i for submit@debbugs.gnu.org; Sat, 09 Jul 2016 11:01:13 -0400 Received: from mail-io0-f172.google.com ([209.85.223.172]:36833) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bLtkl-0005DT-IR; Sat, 09 Jul 2016 11:01:11 -0400 Received: by mail-io0-f172.google.com with SMTP id s93so24449442ioi.3; Sat, 09 Jul 2016 08:01:11 -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=HbRJ64c0HLnpCZkGdZPLRLfx9L7/URWTI4Mtoe1o2lU=; b=P2RqYukqByY59LN6L+KDnty1LDWTzpRaUce+9lDiFOTNhRuDrn2aNelRx9STqmOXwt +pABPRaT9NywzD1faGEDlZnXCrbmb8W7hz+V+HdaGwuLfQ75aet3TMYMhH8lKiayUYhK w5BO2r2gjx/tGM0Re0FLwx317heUO2YE076HUoa8QwpI6Cr8cpoyk2otNVeWZiK3G9qH Gv2atA2n5UgE6k3M0O6cThosfGjrdmNvsby3RcpPnOEe/9xQq0DxN3F4OAGZyqECrgLU jp8NfmXfmUGT5K/SE17ihWw3rEFWf7kj4wIpIryeE8zRGD1XTcGjooZHWO382+T/Wqye dmoA== 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=HbRJ64c0HLnpCZkGdZPLRLfx9L7/URWTI4Mtoe1o2lU=; b=MA/TCxu2uLHXfmbScqBI0dLfLEAWkrS2P0brtrZuyCaZm9xB3VzKxrGbWE9ZYHSHxf 10/9qnmqMFDbSz35Hmd2w/afSKyV4UDmbcayXCz353c451ek4FCCQ5FcNPIWmfM8oI+A tIwWyPblUSYe+L25SCP5vF6+9fCmKg1ve1/V36NIYNxmCI1Si6Kw0+iXp1wkxbH8XUpK ePeasbTTkVUq40SQ/qHR/KZKiTTuauCdgfBRXygGB50w/r4OptTovMCNq9l9uownMlQN fPPeGzkMVTzq/BYZhTHChpOKetX1WJtu4ce27hmdXXlGcrZei3gv8RwiIImmF26sluR+ 0rww== X-Gm-Message-State: ALyK8tKccuDeTO9oWpEO9fa5i9WXNVJBTvyFPmtnAZ8TvVYnikskGIuIx8sUTB/5M1JNDw== X-Received: by 10.107.8.26 with SMTP id 26mr12384347ioi.85.1468076465915; Sat, 09 Jul 2016 08:01:05 -0700 (PDT) Received: from zony (206-188-64-44.cpe.distributel.net. [206.188.64.44]) by smtp.googlemail.com with ESMTPSA id r8sm3487484itb.5.2016.07.09.08.01.04 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 09 Jul 2016 08:01:04 -0700 (PDT) From: npostavs@users.sourceforge.net References: <87d1sqqcbi.fsf@gmail.com> <8760yhdior.fsf@mbork.pl> <87a8i0hel5.fsf@users.sourceforge.net> Date: Sat, 09 Jul 2016 11:01:03 -0400 In-Reply-To: (Artur Malabarba's message of "Tue, 05 Jul 2016 23:06:40 +0000") Message-ID: <87furij1ow.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.93 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) tags 22462 fixed close 22462 25.1 quit Artur Malabarba writes: > Looks fine to me! > Pushed as aac62a67