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

[Eli Zaretskii]

> Cc: 22336@debbugs.gnu.org, Stefan Monnier <monnier@IRO.UMontreal.CA>
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 23 Jan 2016 20:02:36 +0300
> 
> On 01/23/2016 03:51 PM, Eli Zaretskii wrote:
> 
> >    (defmacro cl-defgeneric (name args &rest options-and-methods)
> >      "Create a generic function NAME.
> >    DOC-STRING is the base documentation for this class.  A generic
> >    function has no body, as its purpose is to decide which method body
> >    is appropriate to use.  Specific methods are defined with `cl-defmethod'.
> >    With this implementation the ARGS are currently ignored.
> >    OPTIONS-AND-METHODS currently understands:
> >    - (:documentation DOCSTRING)
> >    - (declare DECLARATIONS)
> >    - (:argument-precedence-order &rest ARGS)
> >    - (:method [QUALIFIERS...] ARGS &rest BODY)
> >    BODY, if present, is used as the body of a default method.
> >
> >    \(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest BODY)"
> >
> > It says a generic function has no body, but the usage info does
> > mention body, and the last part of the doc string says BODY if present
> > is used as the default method.  Or is that the body of :method?
> 
> BODY is "&rest BODY" from the advertised arglist you can see using `M-x 
> describe-function'. It's also visible above in the last line of the 
> docstring.

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.

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

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

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

> > Some omissions are very hard to restore.  The most striking example is
> > TYPE, about which the doc string says nothing at all, and the
> > commentary says just "plain old types".  How could you arrive at the
> > long list that's now in the manual, let alone the type hierarchy that
> > goes with it, except by reading the sources?
> 
> No idea. I was only vaguely aware, if that, of being able to dispatch on 
> atomic types, before reading the manual. Thanks for that.
> 
> But the docstrings don't mention any of the possible values of TYPE 
> (except (eql ...)), not just "plain old" ones. So I'm not clear on what 
> exactly you consider an omission here.

The omission is that nothing is said about what kind of objects can be
used as TYPE.  The idea is clear, but when you want to write code, you
can only understand some of that by looking at the examples, in
particular in cl-generic-tests.el (which is actually the _only_ place
where you can see some -- but unfortunately not all -- of the features
in action).

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

> I think fixing just the things you've mentioned will already be a
> step forward.

Yes, of course.