all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions
@ 2013-08-06  0:06 Drew Adams
  2015-04-13 12:19 ` bug#15031: Status: " Artur Malabarba
  0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2013-08-06  0:06 UTC (permalink / raw)
  To: 15031


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'





^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2015-04-13 21:09 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-08-06  0:06 bug#15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions Drew Adams
2015-04-13 12:19 ` bug#15031: Status: " Artur Malabarba
2015-04-13 14:08   ` Stefan Monnier
2015-04-13 19:56     ` Artur Malabarba
2015-04-13 20:29       ` Eli Zaretskii
2015-04-13 21:09         ` Artur Malabarba

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.