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

[Stefan Monnier <monnier@iro.umontreal.ca>]

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

Not sure what you mean by gibberish.  The function itself is
a one-liner, all it does is (as the docstring says) is that it accesses
the slot called "def-name" of the struct CL-X which is presumed to be of
type `edebug--frame`.

> What significance does it have in edebug?

The "--" indicates it's an internal function.  These are quit often
not documented.

> 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's the name of the argument, as always.  See the earlier line:

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

The choice of `CL-X` as argument name is indeed poor.  It should
probably be ARG or V or X instead.  The use of a `cl-` prefix is
a remnant of the time where we didn't have lexical scoping, IIRC.

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

Indeed, that's unfortunate.  We should improve either `cl-defstruct` or
`find-function` to fix this.

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

This one can be improved by the patch below (which is the kind of patch
you reject in CC-mode, ironically enough).

> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> So, what is a cl-structure-class?

You said so yourself: Since `edebug--frame` is a type of type
`cl-structure-class`, then `cl-structure-class` is a "type of types".
IOW a metaclass.

>      "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).

Since we're in the realm of metaclasses here, it's no wonder that the
info you'll find here won't be very helpful to understand
`edebug--frame-def-name`.

> Following the link just redisplays the current doc string,
> ad infinitum.

Indeed, this metaclass is its own metaclass (that's the usual way to
stop the recursion).


        Stefan


diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index a376067443a..1b4bbb54e59 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -4169,12 +4169,12 @@ edebug-instrumented-backtrace-frames
   "Stack frames of the current Edebug Backtrace buffer with instrumentation.
 This should be a list of `edebug---frame' objects.")
 
-;; Data structure for backtrace frames with information
-;; from Edebug instrumentation found in the backtrace.
 (cl-defstruct
     (edebug--frame
      (:constructor edebug--make-frame)
      (:include backtrace-frame))
+  "Data structure for backtrace frames with information
+from Edebug instrumentation found in the backtrace."
   def-name before-index after-index)
 
 (defun edebug-pop-to-backtrace ()