Re: Poor quality documentation in edebug.el, and recursive documentation.

[Stefan Monnier]

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