bug#22336: 25.0.50; cl-generic.el features are not documented in ELisp manual

[Dmitry Gutov]

On 01/23/2016 08:21 PM, Eli Zaretskii wrote:

> I know.  The point is the stuff contradicts itself, and when I was
> reading this, I needed to decide which part to believe and which to
> discard.  I think I mostly succeeded, albeit at a significant cost;
> I've mentioned these only because you asked about them.

It doesn't exactly contradict itself, though it almost looks that way. 
I've renamed the argument to hopefully make it make more sense.

> > > Anyway, specific methods can evidently be defined by cl-defgeneric as
> > > well, whereas the doc string says they should be defined by
> > > cl-defmethod.  The semantics of :method is never described at all (and
> > > I saw no examples of its usage to inspire me, AFAIR).
> >
> > Is the can/should distinction a problem?
>
> Of course it is.  "Should" is sometimes a synonym of "must".

Actually, the docstring says "methods are defined", not that they should 
be defined. And that's true either way: the :method definitions, and the 
default-body, are still passed to cl-defmethod.

I don't how to improve this part, so I didn't touch it.

> > I think the semantics are easy to guess, but I probably glanced at CL's
> > documentation as well at some point:
>
> I did guess, see what I wrote in the manual.  But I shouldn't have
> needed to guess, I think.

I didn't touch this one either. The current description in the docstring 
might be enough, since I wrong the examples in the previous message just 
by looking at the docstring.

> > > "_The_ dispatch argument", in singular means only one such argument is
> > > possible, which is of course false.
> >
> > Indeed. There's a case to be made for discouraging multiple-argument
> > dispatch ("implemented rather naively"), but the docstring should be
> > corrected anyway.
>
> I thought this was one of the strong points of Lisp-style OOP.

Docstring corrected.

> > cl-defmethod docstring should probably enumerate the possible types
> > (aside from the mentioned ones, TYPE can be (head ...) or a name of
> > cl-struct, like the commentary says).
>
> I think so, yes.  Also, it should at least hint on the hierarchy of
> types.

Types are now mentioned, as well as the word "hierarchy". I've 
referenced a private variable to do that, but I think that's okay in a 
docstring (docstrings are allowed to change between releases).