From: Stefan Monnier <monnier@iro.umontreal.ca>
To: Alan Mackenzie <acm@muc.de>
Cc: emacs-devel@gnu.org
Subject: Re: Poor quality documentation in edebug.el, and recursive documentation.
Date: Fri, 08 May 2020 16:24:28 -0400 [thread overview]
Message-ID: <jwv7dxmtckj.fsf-monnier+emacs@gnu.org> (raw)
In-Reply-To: <20200508195326.GB6705@ACM> (Alan Mackenzie's message of "Fri, 8 May 2020 19:53:26 +0000")
>> > Access slot "def-name" of `edebug--frame' struct CL-X.
[...]
>> It's the name of the argument, as always.
> A typical useful doc string would give information about the semantics
> of the argument, saying, say, "where CL-X is a list".
Hmm... but it does: it says that it's an "`edebug--frame' struct".
> where I was at the beginning of the week. I don't know what a
> "metaclass" is,
It's a generic term from the OO crowd. It's class of a class: in
languages where classes can be manipulated as normal objects, they
themselves belong to a class, called the metaclass (which is hence
itself a class with its own metaclass, etc...).
Luckily you shouldn't need to know any of those things unless you need
to dig into the implementation of Elisp's OO facilities such as
`cl-defstruct`, `eieio`, or `cl-generic`, basically.
> I'm still not sure what a cl-structure-class is and the
> latter needs documenting coherently.
I guess it would be good, yes. In the mean time, just like for a lot of
the CL stuff you can start by looking it up in the HyperSpec:
http://www.lispworks.com/documentation/HyperSpec/Body/t_stu_cl.htm#structure-class
>> > "cl-structure-class is a type (of kind `cl-structure-class')"
>
>> > embedded in approximately 26 lines, none of which shed any light on what
>> > a cl-structure-class is, does, or represents.
>
>> There actual docstring says: "The type of CL structs descriptors."
>> The rest describes the fields of those CL struct descriptors (aka class
>> objects).
>
> It most assuredly does not. It _lists_ those fields - it does not
> describe them. One of these fields, for example, is called named. What
> does named do? What does it represent? What's it for? None of these
> questions is answered. named is undocumented, as are all the other
> fields. Why?
Why do you need to know?
This class is used by `cl-defstruct` and pretty much nothing else, so
presumably if you need to know about it you're hacking on
`cl-defstruct`, and if you're hacking on `cl-defstruct` the first thing
to do is to look up its documentation (unless you know it already,
obviously). After that it should be trivial to guess what this `named`
field is used for.
In your case, you're investigating `edebug--frame`, which should not
depend on the way `cl-defstruct` is implemented. Kind of like looking
at the "vtables" generated by your C++ compiler.
> A better way would be actually to document it.
Be my guest.
Stefan
next prev parent reply other threads:[~2020-05-08 20:24 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-05 20:20 Poor quality documentation in edebug.el, and recursive documentation Alan Mackenzie
2020-05-05 20:39 ` Drew Adams
2020-05-05 21:11 ` Clément Pit-Claudel
2020-05-06 17:01 ` Alan Mackenzie
2020-05-06 18:20 ` Stefan Monnier
2020-05-06 18:34 ` Eli Zaretskii
2020-05-08 19:59 ` Alan Mackenzie
2020-05-09 5:53 ` Eli Zaretskii
2020-05-09 13:47 ` Stefan Monnier
2020-05-09 13:53 ` Eli Zaretskii
2020-05-09 14:56 ` Alan Mackenzie
2020-05-09 15:06 ` tomas
2020-05-09 15:12 ` Andreas Schwab
2020-05-09 15:11 ` Eli Zaretskii
2020-05-06 18:26 ` Stefan Monnier
2020-05-05 22:18 ` Stefan Monnier
2020-05-08 19:53 ` Alan Mackenzie
2020-05-08 20:24 ` Stefan Monnier [this message]
2020-05-12 6:33 ` Madhu
2020-05-12 7:42 ` Eli Zaretskii
2020-05-12 14:04 ` cl-generic misdesign (was: Poor quality documentation in edebug.el, and recursive documentation) Stefan Monnier
2020-05-14 5:03 ` Richard Stallman
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=jwv7dxmtckj.fsf-monnier+emacs@gnu.org \
--to=monnier@iro.umontreal.ca \
--cc=acm@muc.de \
--cc=emacs-devel@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.