all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: 15031@debbugs.gnu.org
Subject: bug#15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions
Date: Mon, 5 Aug 2013 17:06:54 -0700 (PDT)	[thread overview]
Message-ID: <dca353e2-f669-47ef-9f24-2d43e40ef742@default> (raw)


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'





             reply	other threads:[~2013-08-06  0:06 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2013-08-06  0:06 Drew Adams [this message]
2015-04-13 12:19 ` bug#15031: Status: 24.3.50; doc for `(cl-)defstruct' and its generated functions 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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=dca353e2-f669-47ef-9f24-2d43e40ef742@default \
    --to=drew.adams@oracle.com \
    --cc=15031@debbugs.gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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.