bug#43621: 28.0.50; Clean up EIEIO

[Stefan Monnier]

> I'm currently seriously learning and using EIEIO for the first time.
> Here are my findings (so far):
>
> (1) Manual
>
> (1a) (info "(eieio) Introduction")
>
> | Method dispatch
> |      EIEO does not support method dispatch for built-in types and
> |      multiple arguments types.  In other words, method dispatch only
> |      looks at the first argument, and this one must be an EIEIO type.
>
> What's said about dispatching only looking at the first argument is not
> true anymore, right?  And

Indeed.  EIEIO's method dispatch has been thrown away, and instead
cl-generic.el provides it separately from EIEIO.  IOW nowadays "EIEIO"
refers to the facilities surrounding `defclass` but not method dispatch
any more.

Also: cl-generic *can* dispatch on built-in types (and defstruct types).

> | ‘:around’ method tag
> |      This CLOS method tag is non-functional.
> Also not correct any more, right?
> That whole paragraph should be overhauled and adapted to the obviously
> new state of the code I guess.

And moved out of `eieio.texi`.

> | Whenever defclass is used to create a new class, a predicate is created
> | for it, named ‘CLASS-NAME-p’:
> | 
> |  -- Function: CLASS-NAME-p object
> |      Return non-‘nil’ if and only if OBJECT is of the class CLASS-NAME.
>
> I found it surprising that the predicate fails for instances of classes
> that inherit from CLASS-NAME.  If this is intended, I guess this should
> be mentioned...?

Indeed.  It might also be better to promote `(cl-typep EXP '<CLASS>)`
instead of `<CLASS>-p`, which behaves in the more "normal" way.

> (2) `info-lookup' doesn't work for eieio functions.  I guess it should?

It would be nice to make it work, yes.

> (3) Doc of `defclass':
> |  :writer     - A function symbol which will `write' an object's slot.
> I find "`write'" confusing: there is no function `write' (so why quote
> it like this?), and it should better be "set" anyway, since in other
> places (in eieio!) "write" is used as synonym for "print".

Agreed.  It should also be improved to clarify what arguments the writer
takes (IIUC the writer function will take 2 args (the object and
a value for the slot), so the doc needs to clarify in which order those
args are supposed to come).

> Some love is needed here.

Can you provide that love?


        Stefan