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

[Alan Mackenzie <acm@muc.de>]

Hello, Clément.

On Tue, May 05, 2020 at 17:11:43 -0400, Clément Pit-Claudel wrote:
> As far as I know, there's no way to provide documentation for a slot
> of a cl-defstruct.  This sounds like a reasonable feature request
> (you're looking at an auto-generated docstring).

> > I certainly care about what this function does, and the one liner is
> > gibberish. "Access slot "def-name" of ‘edebug--frame’ struct CL-X."

> Really? You're looking at the documentation of a field accessor — can
> it be made much better (sort of writing it by hand)?

It could be made much better.  For a start, it shouldn't be
syntactically ambiguous - It could be talking about "an access slot" or
"accessing the slot".  I think you're telling me that the second is
meant.

And why such a woolly, meaningless word like "access"?  Are we talking
about a read access or a write access here?  It's a bit like writing in
a doc string "_consider_ the input value" - vague and unhelpful, and
calculated to get people writing angry rants on emacs-devel..

Now people have explained it, I see that it means "return the value of
the slot def-name".  That is explicit and says what is done.  Why can
that not be written?

And like you say above, even that much is only a little bit helpful when
the main thing needing documenting is the return value of the function
call - what precisely a def-name is.  After all, in the doc string for
parse-partial-sexp, we don't just say it returns an 11-element list.

And why is the edebug--frame's metasyntactic variable called CL-X?  If
somebody were trying deliberately to be unhelpful, that is what they
would call it.

> It's really the same as the following C function, assuming a struct
> called "backtrace" with a field called "def_name":

>   def_name_t backtrace_def_name (backtrace) { return backtrace.def_name }

If the vagueness were fixed, so that that doc string was self-contained
and informative, I would be happy about it.

-- 
Alan Mackenzie (Nuremberg, Germany).