GNU bug report logs - #15031
24.3.50; doc for `(cl-)defstruct' and its generated functions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15031 in the body.
You can then email your comments to 15031 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; doc for `(cl-)defstruct' and its generated functions
Date: Mon, 5 Aug 2013 17:06:54 -0700 (PDT)

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 <at> gmail.com-20130802160313-rbi3o6322mz0m3ye
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

Message #10 received at 15031 <at> debbugs.gnu.org (full text, mbox):

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: "bug#15031" <15031 <at> debbugs.gnu.org>
Subject: Re: Status: 24.3.50;
 doc for `(cl-)defstruct' and its generated functions
Date: Mon, 13 Apr 2015 13:19:16 +0100

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 <bruce.connor.am <at> gmail.com>
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

Message #13 received at 15031 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Artur Malabarba <bruce.connor.am <at> gmail.com>
Cc: bug#15031 <15031 <at> debbugs.gnu.org>
Subject: Re: bug#15031: Status: 24.3.50;
 doc for `(cl-)defstruct' and its generated functions
Date: Mon, 13 Apr 2015 10:08:28 -0400

> 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

Message #16 received at 15031 <at> debbugs.gnu.org (full text, mbox):

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: bug#15031 <15031 <at> debbugs.gnu.org>
Subject: Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its
 generated functions
Date: Mon, 13 Apr 2015 20:56:43 +0100

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 <monnier <at> iro.umontreal.ca>:
>> 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

Message #19 received at 15031 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: bruce.connor.am <at> gmail.com
Cc: 15031 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#15031: Status: 24.3.50;
 doc for `(cl-)defstruct' and its generated functions
Date: Mon, 13 Apr 2015 23:29:58 +0300

> Date: Mon, 13 Apr 2015 20:56:43 +0100
> From: Artur Malabarba <bruce.connor.am <at> gmail.com>
> Cc: bug#15031 <15031 <at> 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 <at> debbugs.gnu.org.

Message #24 received at 15031-done <at> debbugs.gnu.org (full text, mbox):

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: "bug#15031" <15031-done <at> debbugs.gnu.org>
Subject: Re: bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its
 generated functions
Date: Mon, 13 Apr 2015 22:09:46 +0100

Fixed by the proposed patch.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.