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

[Madhu]

* Stefan Monnier <address@hidden> :
Wrote on Fri, 08 May 2020 16:24:28 -0400:

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

Unfortunately we need to know because we have to deal with your
misdesign of those features and language constructs.  While the concepts
are ostensibky taken from common lisp the implementation shares none of
the spirit of lisp which makes it impossible to work with.

Redefinitions of cl-generics are not possible. I have repeatedly come
across code that uses these features you have introduced, which get into
debug situations where emacs cannot be debugged but needs be killed.

I have  cases (related  debbug) when edbug is essentially unusable and
worse it is so *by your design*. These are not problems that are fixable
without fixing your implementation.
>
>> 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

Again these do not help deal with your perverse idiosyncratic "write
only" implementations which implement your particular nauseous flavour
and opinion of the language which is now forced on elisp.

There isnt any way to submit patches to your code.

The elisp code base has been irrecoverably subverted by your
contributions and there is no way to go back to the pleasurable
debugging-eden which emacs was before you started "contributing"
>
>>> >      "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?

In order to deal with mishbehaving code which uses the features and code
which you have authored.

It is no longer the case that understanding the principles of lisp is
enough to deal with emacs lisp.  Every particular twist in thinking that
you have painfully gone through and opaquely introduced into the code
base has to be unravelled and worked around before a piece of code can
be understood and debugged.


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

Like vtables the intent again is code obfuscation  -  and the lead up to
the its "open source you have the code" taunt


>> A better way would be actually to document it.
>
> Be my guest.

Another taunt - which seems to be the basic motivation for your
"contributions" to emacs.