--- Begin Message ---
|
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 address@hidden
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'
--- End Message ---