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

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

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

The function has no idea what that is.

> After all, in the doc string for parse-partial-sexp, we don't just say
> it returns an 11-element list.

That's a bad analogy: the 11-element list is completely constructed by
`parse-partial-sexp` so it knows very precisely what's in there.

In contrast Edebug's slot-accessor only knows that it returns the
content of that slot.  So it's more like `cl-third` or `nth` which can't
tell you much about their return value other than where it comes from.

This can be addressed by adding a `:documentation` to the slot in
`edebug.el`, tho.  But, for that you'll first need to find someone who
knows/understands that code.  Maybe you'll be the one best placed to add
that doc after you solve the problem that lead you to look at that
function ;-)


        Stefan