'head' specializer for cl-defmethod?

'head' specializer for cl-defmethod?

[Stephen Leake]

project.el uses a 'head' specializer in the dispatching argument of
cl-defmethod.

This use of 'head' is not documented other than in the 'Added elements'
section of the cl-generic.el header comment.

I'd like to change the cl-defmethod doc
string to say:

    Other than a type, TYPE can also be one of the following:

    - `(eql VAL)' - this method will be invoked when the
      argument is `eql' to VAL.

    - `(head VAL)' - this method will be invoked when the `car' of the
      argument is `eql' to VAL


However, that still leaves out the eieio-core specializer `subclass';
I'm not clear how to handle that in the doc string.

I'm guessing the rationale for supporting the 'head' specializer is to
allow using cl-defmethod with objects that are constructed by `cons',
without any cl-defstruct or eieio defclass. That's how it is used in
project.el.


Is there a manual section for cl-defmethod? I don't see one in
doc/misc/cl.texi; perhaps we should add one?

--
-- Stephe

Re: 'head' specializer for cl-defmethod?

[Dmitry Gutov]

On 07/28/2015 03:06 PM, Stephen Leake wrote:

> This use of 'head' is not documented other than in the 'Added elements'
> section of the cl-generic.el header comment.

This statement is also probably outdated: "and all methods of NAME have 
to use the same argument for dispatch". At least I can use a dispatch on 
an argument together with dispatch on &context (which also needs to be 
documented).

> Is there a manual section for cl-defmethod? I don't see one in
> doc/misc/cl.texi; perhaps we should add one?

We should.

Re: 'head' specializer for cl-defmethod?

[Stefan Monnier]

> I'd like to change the cl-defmethod doc
> string to say:

>     Other than a type, TYPE can also be one of the following:

>     - `(eql VAL)' - this method will be invoked when the
>       argument is `eql' to VAL.

>     - `(head VAL)' - this method will be invoked when the `car' of the
>       argument is `eql' to VAL

> However, that still leaves out the eieio-core specializer `subclass';
> I'm not clear how to handle that in the doc string.

Actually, the docstring should be dynamically generated (like the
one of `pcase') to show the various options, since these can be extended
by third party packages.


        Stefan