From unknown Sun Jun 15 08:48:08 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 06 Aug 2013 00:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 15031 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 15031@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.1375747658630 (code B ref -1); Tue, 06 Aug 2013 00:08:02 +0000 Received: (at submit) by debbugs.gnu.org; 6 Aug 2013 00:07:38 +0000 Received: from localhost ([127.0.0.1]:42079 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoL-0000A5-N7 for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:38 -0400 Received: from eggs.gnu.org ([208.118.235.92]:34810) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoI-00009r-Jo for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k9-7f for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:29 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-100.0 required=5.0 tests=BAYES_40, USER_IN_WHITELIST autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:52360) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k5-4J for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:19 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36512) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unu-0002kC-FI for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Unl-0000gv-SN for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:10 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:31564) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unl-0000gk-Dq for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:01 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7606xgC022941 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 6 Aug 2013 00:07:00 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7606wms028131 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 6 Aug 2013 00:06:58 GMT Received: from abhmt108.oracle.com (abhmt108.oracle.com [141.146.116.60]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7606vZW029784 for ; Tue, 6 Aug 2013 00:06:57 GMT MIME-Version: 1.0 Message-ID: Date: Mon, 5 Aug 2013 17:06:54 -0700 (PDT) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6668.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -2.4 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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.4 (--) 1. You can add a doc string to a defstruct structure. But this is very poorly documented. For one thing, it is excluded from the doc string. For another thing what is said about it in (cl) `Structures' is buried so as to be almost imperceptible, and is anyway not clear: -- Macro: cl-defstruct name slots... The `cl-defstruct' form defines a new structure type called NAME, with the specified SLOTS. (The SLOTS may begin with a string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ which documents the structure type.) In the simplest case... ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please help users more than this. 2. The doc string is anyway not used/usable by users! It is the value of property `structure-documentation', but there is no Emacs command that offers it up in *Help*. Please provide this help in some form for users. 3. There is a real problem for each of the functions defined by `(cl-)defstruct': None of them have a doc string. Defstruct itself provides no way to provide a doc string for them. Please provide some simple way to do this, even at the possible cost of deviating from the Common Lisp defstruct definition. We already deviate from it in important ways (it does not define a real type etc.). The least we can do is provide standard Emacs features such as doc strings for the generated functions. Among other things, this will help discoverability. And it will help you understand why, if you do use `C-h f' on such a function name and you click its source link, that takes you to a `defstruct' in the source file. This is not obvious. When you get to the source file you find no defun for the function. In fact, you cannot find the function at all - its name is nowhere to be seen. All of that is "normal", except the fact that Emacs `(cl-)defstruct' does not provide for attaching doc strings to such functions. Yes, a programmer could attach doc in a roundabout way, but they do not seem to be doing so. ;-). In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-08-02 on ODIEONE Bzr revision: 113660 lekktu@gmail.com-20130802160313-rbi3o6322mz0m3ye Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/Devel/emacs/binary --enable-checking=3Dyes,glyphs CFLAGS=3D-O0 -g3 LDFLAGS=3D-Lc:/Devel/emacs/lib CPPFLAGS=3D-Ic:/Devel/emacs/include' From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 08 08:02:02 2014 Received: (at control) by debbugs.gnu.org; 8 Feb 2014 13:02:02 +0000 Received: from localhost ([127.0.0.1]:56682 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7Xl-0002Gx-W2 for submit@debbugs.gnu.org; Sat, 08 Feb 2014 08:02:02 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:57121) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WC7Xj-0002Gj-I5 for control@debbugs.gnu.org; Sat, 08 Feb 2014 08:01:59 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1WC7XU-0002oq-6y for control@debbugs.gnu.org; Sat, 08 Feb 2014 14:01:44 +0100 Date: Sat, 08 Feb 2014 05:00:33 -0800 Message-Id: <87eh3drc7i.fsf@building.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #13572 X-MailScanner-ID: 1WC7XU-0002oq-6y X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392469306.2382@alX5pcsJxinXTNuH3UHFSA X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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.0 (/) merge 13572 15031 From unknown Sun Jun 15 08:48:08 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions References: In-Reply-To: Resent-From: Artur Malabarba Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 13 Apr 2015 12:20:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15031 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "bug#15031" <15031@debbugs.gnu.org> Reply-To: bruce.connor.am@gmail.com Received: via spool by 15031-submit@debbugs.gnu.org id=B15031.14289275762976 (code B ref 15031); Mon, 13 Apr 2015 12:20:03 +0000 Received: (at 15031) by debbugs.gnu.org; 13 Apr 2015 12:19:36 +0000 Received: from localhost ([127.0.0.1]:54847 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhdKm-0000lk-8Q for submit@debbugs.gnu.org; Mon, 13 Apr 2015 08:19:36 -0400 Received: from mail-lb0-f171.google.com ([209.85.217.171]:34711) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhdKk-0000lX-EW for 15031@debbugs.gnu.org; Mon, 13 Apr 2015 08:19:23 -0400 Received: by lbcga7 with SMTP id ga7so57055436lbc.1 for <15031@debbugs.gnu.org>; Mon, 13 Apr 2015 05:19:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:reply-to:sender:date:message-id:subject:from:to :content-type; bh=xm5IdJHO6rD9IF73XLjKjEz4yPo3xHmxwTWWsjmp0ro=; b=oE1bb5yrQ86EHeyW5ARrjXCLEf2cLS9eNEfirTEebcm4TD9K+fHsSVg2lY0kvRQLux ptNq1nz7XyMn+Ab8yOtGWpQi+zixKKCOtFoLlJ3sJD0wtwygVd5EDHvQ1zktktdSM9qm aWXUqVOK4hXIq42oDyYDhJ/HcFe6ceSPFvDswpdHRKVhCCbWkJeC/mkBwy9eDZsv/xpF CRUSAIwa28aQlva30wkth4W/KNrdhmw8lYTnP/3527cgIS1ucpuqZB9HMZY3go7ojaNe kMAdBe3AjNGqH+fkij2DsMQuxGj1D2nWsfHQR1+f1qXb1fwYkXBV6w+Bn6pLAqHtN4Vc lJNg== MIME-Version: 1.0 X-Received: by 10.152.43.110 with SMTP id v14mr12983762lal.4.1428927556373; Mon, 13 Apr 2015 05:19:16 -0700 (PDT) Received: by 10.25.150.131 with HTTP; Mon, 13 Apr 2015 05:19:16 -0700 (PDT) Date: Mon, 13 Apr 2015 13:19:16 +0100 X-Google-Sender-Auth: pc-SgajxCUKZCo5k0CWkFSQmp0E Message-ID: From: Artur Malabarba Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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.0 (/) The following patch should implement bug#15031. It passes make check and seems to work as intended for me. Should I apply? >From 4cac6c23214e8d1a5300dffef78b853954d79e71 Mon Sep 17 00:00:00 2001 From: Artur Malabarba Date: Mon, 13 Apr 2015 13:13:36 +0100 Subject: [PATCH] * lisp/emacs-lisp/cl-macs.el (cl-defstruct): Implement docstrings. Adding a string after a constructor's argument list will use that string as the constructor function docstring. If this string is absent but the struct itself was given a docstring, use that as the constructor's docstring --- lisp/emacs-lisp/cl-macs.el | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el index 41435b8..b91a310 100644 --- a/lisp/emacs-lisp/cl-macs.el +++ b/lisp/emacs-lisp/cl-macs.el @@ -2726,12 +2726,16 @@ non-nil value, that slot cannot be set via `setf'. constrs)) (while constrs (let* ((name (caar constrs)) - (args (cadr (pop constrs))) + (rest (cdr (pop constrs))) + (args (car rest)) + (doc (cadr rest)) (anames (cl--arglist-args args)) (make (cl-mapcar (function (lambda (s d) (if (memq s anames) s d))) slots defaults))) (push `(cl-defsubst ,name (&cl-defs (nil ,@descs) ,@args) + ,@(if doc (list doc) + (if docstring (list docstring))) ,@(if (cl--safe-expr-p `(progn ,@(mapcar #'cl-second descs))) '((declare (side-effect-free t)))) (,(or type #'vector) ,@make)) -- 2.3.5 From unknown Sun Jun 15 08:48:08 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 13 Apr 2015 14:09:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15031 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Artur Malabarba Cc: bug#15031 <15031@debbugs.gnu.org> Received: via spool by 15031-submit@debbugs.gnu.org id=B15031.142893413413560 (code B ref 15031); Mon, 13 Apr 2015 14:09:02 +0000 Received: (at 15031) by debbugs.gnu.org; 13 Apr 2015 14:08:54 +0000 Received: from localhost ([127.0.0.1]:55088 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Yhf2k-0003We-0J for submit@debbugs.gnu.org; Mon, 13 Apr 2015 10:08:54 -0400 Received: from mercure.iro.umontreal.ca ([132.204.24.67]:53367) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Yhf2i-0003WX-HW for 15031@debbugs.gnu.org; Mon, 13 Apr 2015 10:08:52 -0400 Received: from hidalgo.iro.umontreal.ca (hidalgo.iro.umontreal.ca [132.204.27.50]) by mercure.iro.umontreal.ca (Postfix) with ESMTP id 482A285F2A; Mon, 13 Apr 2015 10:08:52 -0400 (EDT) Received: from lechon.iro.umontreal.ca (lechon.iro.umontreal.ca [132.204.27.242]) by hidalgo.iro.umontreal.ca (Postfix) with ESMTP id 238CD1E5B8D; Mon, 13 Apr 2015 10:08:29 -0400 (EDT) Received: by lechon.iro.umontreal.ca (Postfix, from userid 20848) id 03161B4122; Mon, 13 Apr 2015 10:08:28 -0400 (EDT) From: Stefan Monnier Message-ID: References: Date: Mon, 13 Apr 2015 10:08:28 -0400 In-Reply-To: (Artur Malabarba's message of "Mon, 13 Apr 2015 13:19:16 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-DIRO-MailScanner-Information: Please contact the ISP for more information X-DIRO-MailScanner: Found to be clean X-DIRO-MailScanner-SpamCheck: n'est pas un polluriel, SpamAssassin (score=-2.82, requis 5, autolearn=not spam, ALL_TRUSTED -2.82, MC_TSTLAST 0.00) X-DIRO-MailScanner-From: monnier@iro.umontreal.ca X-Spam-Status: No X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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 (--) > The following patch should implement bug#15031. It passes make check > and seems to work as intended for me. Should I apply? Looks OK, yes. Tho you might like to check that doc is a string. Stefan From unknown Sun Jun 15 08:48:08 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions Resent-From: Artur Malabarba Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 13 Apr 2015 19:57:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15031 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Stefan Monnier Cc: bug#15031 <15031@debbugs.gnu.org> Reply-To: bruce.connor.am@gmail.com Received: via spool by 15031-submit@debbugs.gnu.org id=B15031.142895501213946 (code B ref 15031); Mon, 13 Apr 2015 19:57:02 +0000 Received: (at 15031) by debbugs.gnu.org; 13 Apr 2015 19:56:52 +0000 Received: from localhost ([127.0.0.1]:55196 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhkTT-0003co-DW for submit@debbugs.gnu.org; Mon, 13 Apr 2015 15:56:51 -0400 Received: from mail-lb0-f178.google.com ([209.85.217.178]:34276) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhkTR-0003cY-Si for 15031@debbugs.gnu.org; Mon, 13 Apr 2015 15:56:50 -0400 Received: by lbcga7 with SMTP id ga7so68198643lbc.1 for <15031@debbugs.gnu.org>; Mon, 13 Apr 2015 12:56:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:reply-to:sender:in-reply-to:references:date:message-id :subject:from:to:cc:content-type; bh=yLrQ4jxvjw1KegSvSxCsHlBd0IQwuoDFccjUuYDjfJs=; b=J5E7Nl/jX6pZoe+WUmLMj5Cefq4kR103Dg42PhuJvpZC+YUsfNgjV7/3nkJu2Gy93m iaqetSxRNGSa+9jwii3yGDXMv7flZVUKQXh/UAYs3wz0gKgzwhpExVHf9J28F0BQCK1B plawLUEaq6e+6+eNGpAL+uChLCGChaLmHT1i6jIZVPgtNGgNCNWaRdOJ+9Q0BvY1ZzWl mwZxrAutSHEZml79UHyNfoaibeAYb+OUHe8L48Y51vPZzk3Eg3V8d8kmoyLzVB++uN42 JLdda5+yhrJPMWumm2o9PjNNAwVx9OW6pCXU/Ml3cCDij7uV3GyQwl0F7SOLswWYe4MD MiIg== MIME-Version: 1.0 X-Received: by 10.152.43.110 with SMTP id v14mr14715623lal.4.1428955003922; Mon, 13 Apr 2015 12:56:43 -0700 (PDT) Received: by 10.25.150.131 with HTTP; Mon, 13 Apr 2015 12:56:43 -0700 (PDT) In-Reply-To: References: Date: Mon, 13 Apr 2015 20:56:43 +0100 X-Google-Sender-Auth: qb7xma6yuIx51qmQna1t7NIQIaE Message-ID: From: Artur Malabarba Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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 (/) Done. Btw, what's the right procedure to notify that a bug has been addressed? Is there some sort of integration between debbugs and commit messages, or should I just send a message like this one saying it's fixed? 2015-04-13 15:08 GMT+01:00 Stefan Monnier : >> The following patch should implement bug#15031. It passes make check >> and seems to work as intended for me. Should I apply? > > Looks OK, yes. Tho you might like to check that doc is a string. > > > Stefan From unknown Sun Jun 15 08:48:08 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 13 Apr 2015 20:30:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15031 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: bruce.connor.am@gmail.com Cc: 15031@debbugs.gnu.org, monnier@iro.umontreal.ca Reply-To: Eli Zaretskii Received: via spool by 15031-submit@debbugs.gnu.org id=B15031.142895699816857 (code B ref 15031); Mon, 13 Apr 2015 20:30:03 +0000 Received: (at 15031) by debbugs.gnu.org; 13 Apr 2015 20:29:58 +0000 Received: from localhost ([127.0.0.1]:55229 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhkzW-0004No-CV for submit@debbugs.gnu.org; Mon, 13 Apr 2015 16:29:58 -0400 Received: from mtaout20.012.net.il ([80.179.55.166]:34450) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhkzU-0004Na-31 for 15031@debbugs.gnu.org; Mon, 13 Apr 2015 16:29:57 -0400 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0NMR00G00HXO6200@a-mtaout20.012.net.il> for 15031@debbugs.gnu.org; Mon, 13 Apr 2015 23:29:48 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NMR00GG0I9O5K20@a-mtaout20.012.net.il>; Mon, 13 Apr 2015 23:29:48 +0300 (IDT) Date: Mon, 13 Apr 2015 23:29:58 +0300 From: Eli Zaretskii In-reply-to: X-012-Sender: halo1@inter.net.il Message-id: <83d237db5l.fsf@gnu.org> References: X-Spam-Score: 1.0 (+) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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: 1.0 (+) > Date: Mon, 13 Apr 2015 20:56:43 +0100 > From: Artur Malabarba > Cc: bug#15031 <15031@debbugs.gnu.org> > > Btw, what's the right procedure to notify that a bug has been addressed? See admin/notes/bugtracker: you need to send email to it. > Is there some sort of integration between debbugs and commit messages, No. > or should I just send a message like this one saying it's fixed? Send mail to NNNNN-done@debbugs.gnu.org. From unknown Sun Jun 15 08:48:08 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.503 (Entity 5.503) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Drew Adams Subject: bug#15031: closed (Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions) Message-ID: References: X-Gnu-PR-Message: they-closed 15031 X-Gnu-PR-Package: emacs Reply-To: 15031@debbugs.gnu.org Date: Mon, 13 Apr 2015 21:10:07 +0000 Content-Type: multipart/mixed; boundary="----------=_1428959407-20736-1" This is a multi-part message in MIME format... ------------=_1428959407-20736-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 15031@debbugs.gnu.org. --=20 15031: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D15031 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1428959407-20736-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 15031-done) by debbugs.gnu.org; 13 Apr 2015 21:09:54 +0000 Received: from localhost ([127.0.0.1]:55283 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhlcA-0005Nh-8S for submit@debbugs.gnu.org; Mon, 13 Apr 2015 17:09:54 -0400 Received: from mail-lb0-f178.google.com ([209.85.217.178]:33376) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Yhlc8-0005NR-11 for 15031-done@debbugs.gnu.org; Mon, 13 Apr 2015 17:09:52 -0400 Received: by lbbzk7 with SMTP id zk7so69601911lbb.0 for <15031-done@debbugs.gnu.org>; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:reply-to:sender:in-reply-to:references:date:message-id :subject:from:to:content-type; bh=fQz+29DvQyf/YwcPWzFtns2nMr3YEEzo2M0S+5nH1WA=; b=oVKHmPnEusjCb6D9SJ1iAii/yU7drKNGlKvOkWXWpNvWNqjXds6RRQLKxCnkPEOdgF c7nq3emnGOseOEQ6l1+XEJEslTE5UNEPJfVp5yQ75tNriEiigYQ42EHqCRUxfhk3tDKP 87Hi4NOTz5aS0eYvYLXwLT9QK10VY27rWQ/8YyFWhXV2aHX+GgpyNH2Bb+Zn1X2hkrvV untaaWtFnte1r4HSto4PH+5CyS1wNfp7RSNJnkciq74sQDKe55WvHwwCO+DPRME0fwwT GnHkpEMbeqq4cGnl4D30Jkzg9ygZJvkxRyVyhDCnXQcJKMQMkBw993Xme/hzOXhpxWba It0w== MIME-Version: 1.0 X-Received: by 10.152.2.105 with SMTP id 9mr13247925lat.16.1428959386186; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) Received: by 10.25.150.131 with HTTP; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) In-Reply-To: <83d237db5l.fsf@gnu.org> References: <83d237db5l.fsf@gnu.org> Date: Mon, 13 Apr 2015 22:09:46 +0100 X-Google-Sender-Auth: UwYJgMQZiKjk6X9qkUnGmjShTRw Message-ID: Subject: Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions From: Artur Malabarba To: "bug#15031" <15031-done@debbugs.gnu.org> Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 15031-done X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: bruce.connor.am@gmail.com 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 (/) Fixed by the proposed patch. ------------=_1428959407-20736-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 6 Aug 2013 00:07:38 +0000 Received: from localhost ([127.0.0.1]:42079 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoL-0000A5-N7 for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:38 -0400 Received: from eggs.gnu.org ([208.118.235.92]:34810) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoI-00009r-Jo for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k9-7f for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:29 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-100.0 required=5.0 tests=BAYES_40, USER_IN_WHITELIST autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:52360) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k5-4J for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:19 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36512) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unu-0002kC-FI for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Unl-0000gv-SN for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:10 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:31564) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unl-0000gk-Dq for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:01 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7606xgC022941 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 6 Aug 2013 00:07:00 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7606wms028131 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 6 Aug 2013 00:06:58 GMT Received: from abhmt108.oracle.com (abhmt108.oracle.com [141.146.116.60]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7606vZW029784 for ; Tue, 6 Aug 2013 00:06:57 GMT MIME-Version: 1.0 Message-ID: Date: Mon, 5 Aug 2013 17:06:54 -0700 (PDT) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 24.3.50; doc for `(cl-)defstruct' and its generated functions X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6668.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -2.4 (--) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 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.4 (--) 1. You can add a doc string to a defstruct structure. But this is very poorly documented. For one thing, it is excluded from the doc string. For another thing what is said about it in (cl) `Structures' is buried so as to be almost imperceptible, and is anyway not clear: -- Macro: cl-defstruct name slots... The `cl-defstruct' form defines a new structure type called NAME, with the specified SLOTS. (The SLOTS may begin with a string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ which documents the structure type.) In the simplest case... ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please help users more than this. 2. The doc string is anyway not used/usable by users! It is the value of property `structure-documentation', but there is no Emacs command that offers it up in *Help*. Please provide this help in some form for users. 3. There is a real problem for each of the functions defined by `(cl-)defstruct': None of them have a doc string. Defstruct itself provides no way to provide a doc string for them. Please provide some simple way to do this, even at the possible cost of deviating from the Common Lisp defstruct definition. We already deviate from it in important ways (it does not define a real type etc.). The least we can do is provide standard Emacs features such as doc strings for the generated functions. Among other things, this will help discoverability. And it will help you understand why, if you do use `C-h f' on such a function name and you click its source link, that takes you to a `defstruct' in the source file. This is not obvious. When you get to the source file you find no defun for the function. In fact, you cannot find the function at all - its name is nowhere to be seen. All of that is "normal", except the fact that Emacs `(cl-)defstruct' does not provide for attaching doc strings to such functions. Yes, a programmer could attach doc in a roundabout way, but they do not seem to be doing so. ;-). In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-08-02 on ODIEONE Bzr revision: 113660 lekktu@gmail.com-20130802160313-rbi3o6322mz0m3ye Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/Devel/emacs/binary --enable-checking=3Dyes,glyphs CFLAGS=3D-O0 -g3 LDFLAGS=3D-Lc:/Devel/emacs/lib CPPFLAGS=3D-Ic:/Devel/emacs/include' ------------=_1428959407-20736-1-- From unknown Sun Jun 15 08:48:08 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.503 (Entity 5.503) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: "Drew Adams" Subject: bug#13572: closed (Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions) Message-ID: References: <25708670B28E4172A0FC0979D00984FC@us.oracle.com> X-Gnu-PR-Message: they-closed 13572 X-Gnu-PR-Package: emacs Reply-To: 13572@debbugs.gnu.org Date: Mon, 13 Apr 2015 21:10:09 +0000 Content-Type: multipart/mixed; boundary="----------=_1428959409-20736-3" This is a multi-part message in MIME format... ------------=_1428959409-20736-3 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #15031: 24.3.50; `describe-function' -> "This function has a compiler macro= ..." which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 13572@debbugs.gnu.org. --=20 15031: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D15031 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1428959409-20736-3 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 15031-done) by debbugs.gnu.org; 13 Apr 2015 21:09:54 +0000 Received: from localhost ([127.0.0.1]:55283 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YhlcA-0005Nh-8S for submit@debbugs.gnu.org; Mon, 13 Apr 2015 17:09:54 -0400 Received: from mail-lb0-f178.google.com ([209.85.217.178]:33376) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Yhlc8-0005NR-11 for 15031-done@debbugs.gnu.org; Mon, 13 Apr 2015 17:09:52 -0400 Received: by lbbzk7 with SMTP id zk7so69601911lbb.0 for <15031-done@debbugs.gnu.org>; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:reply-to:sender:in-reply-to:references:date:message-id :subject:from:to:content-type; bh=fQz+29DvQyf/YwcPWzFtns2nMr3YEEzo2M0S+5nH1WA=; b=oVKHmPnEusjCb6D9SJ1iAii/yU7drKNGlKvOkWXWpNvWNqjXds6RRQLKxCnkPEOdgF c7nq3emnGOseOEQ6l1+XEJEslTE5UNEPJfVp5yQ75tNriEiigYQ42EHqCRUxfhk3tDKP 87Hi4NOTz5aS0eYvYLXwLT9QK10VY27rWQ/8YyFWhXV2aHX+GgpyNH2Bb+Zn1X2hkrvV untaaWtFnte1r4HSto4PH+5CyS1wNfp7RSNJnkciq74sQDKe55WvHwwCO+DPRME0fwwT GnHkpEMbeqq4cGnl4D30Jkzg9ygZJvkxRyVyhDCnXQcJKMQMkBw993Xme/hzOXhpxWba It0w== MIME-Version: 1.0 X-Received: by 10.152.2.105 with SMTP id 9mr13247925lat.16.1428959386186; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) Received: by 10.25.150.131 with HTTP; Mon, 13 Apr 2015 14:09:46 -0700 (PDT) In-Reply-To: <83d237db5l.fsf@gnu.org> References: <83d237db5l.fsf@gnu.org> Date: Mon, 13 Apr 2015 22:09:46 +0100 X-Google-Sender-Auth: UwYJgMQZiKjk6X9qkUnGmjShTRw Message-ID: Subject: Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions From: Artur Malabarba To: "bug#15031" <15031-done@debbugs.gnu.org> Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 15031-done X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: bruce.connor.am@gmail.com 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 (/) Fixed by the proposed patch. ------------=_1428959409-20736-3 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 28 Jan 2013 02:39:50 +0000 Received: from localhost ([127.0.0.1]:51877 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TzedR-0007zG-Se for submit@debbugs.gnu.org; Sun, 27 Jan 2013 21:39:50 -0500 Received: from eggs.gnu.org ([208.118.235.92]:54381) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TzedQ-0007zA-QQ for submit@debbugs.gnu.org; Sun, 27 Jan 2013 21:39:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Tzed2-00008U-Rw for submit@debbugs.gnu.org; Sun, 27 Jan 2013 21:39:25 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-104.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_WHITELIST autolearn=unavailable version=3.3.2 Received: from lists.gnu.org ([208.118.235.17]:43448) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tzed2-00008P-Ou for submit@debbugs.gnu.org; Sun, 27 Jan 2013 21:39:24 -0500 Received: from eggs.gnu.org ([208.118.235.92]:37509) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tzed1-0004Xh-S9 for bug-gnu-emacs@gnu.org; Sun, 27 Jan 2013 21:39:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Tzed0-00007z-VV for bug-gnu-emacs@gnu.org; Sun, 27 Jan 2013 21:39:23 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:49103) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Tzed0-00007s-OL for bug-gnu-emacs@gnu.org; Sun, 27 Jan 2013 21:39:22 -0500 Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id r0S2dKN2012963 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 28 Jan 2013 02:39:21 GMT Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r0S2dKDp005492 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 28 Jan 2013 02:39:20 GMT Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r0S2dK2Q023251 for ; Sun, 27 Jan 2013 20:39:20 -0600 Received: from dradamslap1 (/71.202.147.44) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 27 Jan 2013 18:39:19 -0800 From: "Drew Adams" To: Subject: 24.3.50; `describe-function' -> "This function has a compiler macro..." Date: Sun, 27 Jan 2013 18:39:10 -0800 Message-ID: <25708670B28E4172A0FC0979D00984FC@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac39AKaRPAFJtGLMQ6Co8laO42ih6g== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 208.118.235.17 X-Spam-Score: -3.5 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -4.3 (----) C-h f registerv-p The help says only this: This function has a compiler macro in `register.el'. This help is not very helpful. I, for one, do not understand it. Searching `register.el' does not turn up any definition of `registerv-p', that I can find. There are only invocations of the function in that file. And searching the Elisp manual for "compiler macro" turns up nothing. Perhaps this concept needs to be documented. Digging into help-fns.el I find that the test that produces this helpful message is (get function 'compiler-macro-file). But I haven't tried to search further to see what can be understood about this. Please document all of the constructs that you use in the Emacs source code, including this one. In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600) of 2013-01-25 on ODIEONE Bzr revision: 111604 eliz@gnu.org-20130125143821-1ykj7ia1qjojjjnp Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.7) --no-opt --enable-checking --cflags -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib' ------------=_1428959409-20736-3--