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

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

[Drew Adams]

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=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions

[Artur Malabarba]

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@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

bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions

[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

bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions

[Artur Malabarba]

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@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

bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions

[Eli Zaretskii]

> Date: Mon, 13 Apr 2015 20:56:43 +0100
> From: Artur Malabarba <bruce.connor.am@gmail.com>
> 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.

bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions

[Artur Malabarba]

Fixed by the proposed patch.