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

[Alan Mackenzie <acm@muc.de>]

In the master branch in function edebug--backtrace-goto-source there is a
call to function edebug--frame-def-name.  The doc string of the latter
is, in its entirety:

    edebug--frame-def-name is a compiled Lisp function in `edebug.el'.

    (edebug--frame-def-name CL-X)

      This function has a compiler macro `edebug--frame-def-name--cmacro'.
      This function does not change global state, including the match data.

    Access slot "def-name" of `edebug--frame' struct CL-X.

Huh?  Do I really care about whether it has a compiler macro?  I
certainly care about what this function does, and the one liner is
gibberish.  "Access slot "def-name" .... struct CL-X."?  Is "Access" a
verb or an adjective, here?  What on earth is a "def-name"?  What
significance does it have in edebug?  What is the return value of this
function?  All of these points are left open by this alleged doc string.
What does CL-X mean?

It carries on.  If you put point over the `edebug.el' and type <CR>, it
doesn't go to the defining function, throwing an error instead.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

It caries on further, and if anything, gets steadily worse: put point
over `edebug-frame' and hit <CR>.  It leads to another vacuous doc
string.  An `edebug-frame' is a type.  Great!  It is a type of type
cl-structure-class, whatever one of those is.  There follows a columnar
list of something, and some gobbledegook about "Specialized Methods",
whatever they are.  I don't understand it.

At least the link to the source works for `edebug-frame'.  The source
contains NO documentation string, and it is not obvious what an
edebug-frame is or does.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

So, what is a cl-structure-class?  From the most recent doc-string,
follow the link.  We get to another doc string, a profoundly useless one,
which reads

     "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.  Following the link just
redisplays the current doc string, ad infinitum.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Maybe RTFMing will shed light.  Nope: in cl.info, there's not a single
mention of cl-structure-class.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

DOC STRINGS MATTER!!!  Not, perhaps in every last minor private function
in every package, but in obscure cl-* functions used widely throughout
Emacs they most definitely do.

Can we please stop writing code like this?  For everybody but an elite
who likes this sort of thing, it's a massive time sink.  As this sort of
code is steadily proliferated through Emacs, the amount of code readily
maintainable by anybody steadily decreases.  Only this elite can
effectively manage stuff with cl-structure-class in it.  This is not good
for Emacs.

I don't doubt I could, by reading the code, work out what
cl-structure-class does.  But it would be time consuming and dreary, I
would soon forget it again, and I've got plenty of other things to do.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

So, would somebody who likes it please document cl-structure-class and
its friends adequately?

Would somebody please add a doc string, a good one, to `edebug-frame'?

Thanks!

-- 
Alan Mackenzie (Nuremberg, Germany).