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

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

[Eli Zaretskii]

It looks like the new features, implemented by cl-generic.el and used
quite a lot in our sources, are not documented in any manual.  Their doc
strings are impenetrable to anyone who isn't already familiar with CLOS
multiple-dispatch generics, as they use terminology ("specializers",
"generalizers", "dispatch", etc.) not explained anywhere.  NEWS has
this to say about them:

  ** cl-generic.el provides CLOS-style multiple-dispatch generic functions.

That's the entire text of the entry.  It diesn't even mention the 2
entry points, 'cl-defgeneric' and 'cl-defmethod'.

The generics should be prominently documented either in the ELisp
manual.  Emacs 25.1 should have them documented, due to their wide usage
in the core packages and elsewhere.



In GNU Emacs 25.0.50.281 (i686-pc-mingw32)
 of 2016-01-08 built on HOME-C4E4A596F7
Repository revision: 1a6b0846b5fbf08aa4288ae9e47c59cfca30459f
Windowing system distributor 'Microsoft Corp.', version 5.1.2600
Configured using:
 'configure --prefix=/d/usr --enable-checking=yes,glyphs --with-wide-int
 --with-modules 'CFLAGS=-O0 -gdwarf-4 -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS MODULES

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1255

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message dired format-spec rfc822 mml
mml-sec epg epg-config gnus-util mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util help-fns help-mode easymenu cl-loaddefs pcase
cl-lib mail-prsvr mail-utils time-date mule-util tooltip eldoc electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel dos-w32 ls-lisp
disp-table w32-win w32-vars term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list newcomment elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
mouse jit-lock font-lock syntax facemenu font-core frame cl-generic cham
georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese charscript case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer cl-preloaded nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote w32notify w32 multi-tty
make-network-process emacs)

Memory information:
((conses 16 92854 5930)
 (symbols 56 20660 0)
 (miscs 48 36 107)
 (strings 16 17691 6375)
 (string-bytes 1 438680)
 (vectors 16 12303)
 (vector-slots 8 418992 3863)
 (floats 8 162 76)
 (intervals 40 261 118)
 (buffers 856 11))

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

[Eli Zaretskii]

> Date: Sat, 09 Jan 2016 11:06:52 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> The generics should be prominently documented either in the ELisp
> manual.  Emacs 25.1 should have them documented, due to their wide usage
> in the core packages and elsewhere.

I made this bug block v25.1 release.

If someone can describe the relevant stuff, but is afraid the text
won't be up to the standards of the manual, or isn't proficient enough
with Texinfo, please send the text, and I volunteer to edit it into
the appropriate form for inclusion in the manual.

IOW, don't bother yourself with technicalities; just produce the
contents.

TIA

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

[Eli Zaretskii]

Ping!  Would someone please volunteer to write some documentation of
these?

> Date: Sat, 09 Jan 2016 11:06:52 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> 
> It looks like the new features, implemented by cl-generic.el and used
> quite a lot in our sources, are not documented in any manual.  Their doc
> strings are impenetrable to anyone who isn't already familiar with CLOS
> multiple-dispatch generics, as they use terminology ("specializers",
> "generalizers", "dispatch", etc.) not explained anywhere.  NEWS has
> this to say about them:
> 
>   ** cl-generic.el provides CLOS-style multiple-dispatch generic functions.
> 
> That's the entire text of the entry.  It diesn't even mention the 2
> entry points, 'cl-defgeneric' and 'cl-defmethod'.
> 
> The generics should be prominently documented either in the ELisp
> manual.  Emacs 25.1 should have them documented, due to their wide usage
> in the core packages and elsewhere.
> 
> 
> 
> In GNU Emacs 25.0.50.281 (i686-pc-mingw32)
>  of 2016-01-08 built on HOME-C4E4A596F7
> Repository revision: 1a6b0846b5fbf08aa4288ae9e47c59cfca30459f
> Windowing system distributor 'Microsoft Corp.', version 5.1.2600
> Configured using:
>  'configure --prefix=/d/usr --enable-checking=yes,glyphs --with-wide-int
>  --with-modules 'CFLAGS=-O0 -gdwarf-4 -g3''
> 
> Configured features:
> XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
> TOOLKIT_SCROLL_BARS MODULES
> 
> Important settings:
>   value of $LANG: ENU
>   locale-coding-system: cp1255
> 
> Major mode: Lisp Interaction
> 
> Minor modes in effect:
>   tooltip-mode: t
>   global-eldoc-mode: t
>   electric-indent-mode: t
>   mouse-wheel-mode: t
>   tool-bar-mode: t
>   menu-bar-mode: t
>   file-name-shadow-mode: t
>   global-font-lock-mode: t
>   font-lock-mode: t
>   blink-cursor-mode: t
>   auto-composition-mode: t
>   auto-encryption-mode: t
>   auto-compression-mode: t
>   line-number-mode: t
>   transient-mark-mode: t
> 
> Recent messages:
> For information about GNU Emacs and the GNU system, type C-h C-a.
> 
> Load-path shadows:
> None found.
> 
> Features:
> (shadow sort mail-extr emacsbug message dired format-spec rfc822 mml
> mml-sec epg epg-config gnus-util mm-decode mm-bodies mm-encode
> mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
> rfc2045 ietf-drums mm-util help-fns help-mode easymenu cl-loaddefs pcase
> cl-lib mail-prsvr mail-utils time-date mule-util tooltip eldoc electric
> uniquify ediff-hook vc-hooks lisp-float-type mwheel dos-w32 ls-lisp
> disp-table w32-win w32-vars term/common-win tool-bar dnd fontset image
> regexp-opt fringe tabulated-list newcomment elisp-mode lisp-mode
> prog-mode register page menu-bar rfn-eshadow timer select scroll-bar
> mouse jit-lock font-lock syntax facemenu font-core frame cl-generic cham
> georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
> korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
> european ethiopic indian cyrillic chinese charscript case-table epa-hook
> jka-cmpr-hook help simple abbrev minibuffer cl-preloaded nadvice
> loaddefs button faces cus-face macroexp files text-properties overlay
> sha1 md5 base64 format env code-pages mule custom widget
> hashtable-print-readable backquote w32notify w32 multi-tty
> make-network-process emacs)
> 
> Memory information:
> ((conses 16 92854 5930)
>  (symbols 56 20660 0)
>  (miscs 48 36 107)
>  (strings 16 17691 6375)
>  (string-bytes 1 438680)
>  (vectors 16 12303)
>  (vector-slots 8 418992 3863)
>  (floats 8 162 76)
>  (intervals 40 261 118)
>  (buffers 856 11))
> 
> 
> 
> 

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

[Eli Zaretskii]

> Date: Sat, 16 Jan 2016 10:25:39 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> Ping!  Would someone please volunteer to write some documentation of
> these?

Since so many people volunteered that I had trouble picking up the
best one, I did this myself in commit 849a314.

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

[Dmitry Gutov]

On 01/23/2016 12:17 AM, Eli Zaretskii wrote:

> Since so many people volunteered that I had trouble picking up the
> best one, I did this myself in commit 849a314.

Thank you, Eli. I gave it a once-over, and it's a good read.

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

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 23 Jan 2016 08:29:50 +0300
> 
> On 01/23/2016 12:17 AM, Eli Zaretskii wrote:
> 
> > Since so many people volunteered that I had trouble picking up the
> > best one, I did this myself in commit 849a314.
> 
> Thank you, Eli. I gave it a once-over, and it's a good read.

Thanks for reviewing.  Getting all that stuff together was a
non-trivial feat.

Note that the doc strings don't tell everything I wrote, and sometimes
seem to say inaccurate or even contradictory things, so if what I
wrote correctly describes what the implementation actually does, the
doc strings (as well as some of the comments) in cl-generic.el should
probably be brought in line with the reality.

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

[Dmitry Gutov]

On 01/23/2016 09:06 AM, Eli Zaretskii wrote:

> Note that the doc strings don't tell everything I wrote, and sometimes
> seem to say inaccurate or even contradictory things, so if what I
> wrote correctly describes what the implementation actually does, the
> doc strings (as well as some of the comments) in cl-generic.el should
> probably be brought in line with the reality.

Could you give an example of them being wrong? I only things omitted in 
docstrings (but which can be inferred from the commentary, such as 
dispatch on types such as integer, string, and so on).

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

[Eli Zaretskii]

> Cc: 22336@debbugs.gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 23 Jan 2016 11:20:03 +0300
> 
> On 01/23/2016 09:06 AM, Eli Zaretskii wrote:
> 
> > Note that the doc strings don't tell everything I wrote, and sometimes
> > seem to say inaccurate or even contradictory things, so if what I
> > wrote correctly describes what the implementation actually does, the
> > doc strings (as well as some of the comments) in cl-generic.el should
> > probably be brought in line with the reality.
> 
> Could you give an example of them being wrong?

  (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?
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).

  (defmacro cl-defmethod (name args &rest body)
    "Define a new method for generic function NAME.
  I.e. it defines the implementation of NAME to use for invocations where the
  value of the dispatch argument matches the specified TYPE.
  The dispatch argument has to be one of the mandatory arguments, and
  all methods of NAME have to use the same argument for dispatch.
  The dispatch argument and TYPE are specified in ARGS where the corresponding
  formal argument appears as (VAR TYPE) rather than just VAR.

  The optional second argument QUALIFIER is a specifier that
  modifies how the method is combined with other methods, including:
     :before  - Method will be called before the primary
     :after   - Method will be called after the primary
     :around  - Method will be called around everything else
  The absence of QUALIFIER means this is a \"primary\" method.

  Other than a type, TYPE can also be of the form `(eql VAL)' in
  which case this method will be invoked when the argument is `eql' to VAL.

  \(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"

"_The_ dispatch argument", in singular means only one such argument is
possible, which is of course false.  The &context dispatch has a
slightly different syntax, but it isn't mentioned here at all, which
makes the description of (VAR TYPE) incorrect in that case.

>                                           I only things omitted in 
> docstrings (but which can be inferred from the commentary, such as 
> dispatch on types such as integer, string, and so on).

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?

As another example, the ":extra STRING" feature is mentioned, but
without any details; I couldn't understand how to use it in practice
(it is not used in the tests, either).

And I don't recommend believing the commentary too much, either.
E.g., what it says about &context in several places is contradictory:

  ;;   E.g. (foo &context (major-mode (eql c-mode))) is an arglist specifying
  ;;   that this method will only be applicable when `major-mode' has value
  ;;   `c-mode'.

and then:

  ;; - then define a context-rewriter so you can write
  ;;   "&context (major-mode c-mode)" rather than
  ;;   "&context (major-mode (derived-mode c-mode))".

and even

  ;; TODO:
  ;;
  ;; - A way to dispatch on the context (e.g. the major-mode, some global
  ;;   variable, you name it).

which makes you think it isn't even implemented...  Also, there's
something about derived-mode there, but it's so contrived and devoid
of examples, that I didn't even put that in the manual.

There were others I was only too happy to forget.  I needed to read
the CLOS documentation to make sense of some things.  Of course,
cl-generic.el doesn't implement all of CLOS, and then adds extension
that are not in CLOS, so even CLOS documentation only helps up to a
point.

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

[Dmitry Gutov]

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. The phrase "generic function has no body" is trying to say, 
apparently, that a generic function is not really a function (but more 
like a multi-dimensional hash-table), and the default method, which you 
_can_ provide inside the cl-defgeneric form, is the default value in 
that table.

Usage example:

(cl-defgeneric foo (a)
   10)

(cl-defmethod foo ((a integer))
   (* 20 a))

(foo 'a)
10

(foo 4)
80

> 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? Yes, when in doubt, 
cl-defmethod should be used, but one can define them inline as well.

I think the semantics are easy to guess, but I probably glanced at CL's 
documentation as well at some point:

(cl-defgeneric foo (a)
   (:method ((s string)) "stringy!")
   (:method ((a array)) :four)
   10)

(foo "s")
"stringy!"

(foo [1 2 3])
:four

TBH, I haven't used this even once in practice.

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

> The &context dispatch has a
> slightly different syntax, but it isn't mentioned here at all, which
> makes the description of (VAR TYPE) incorrect in that case.

Also true.

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

> As another example, the ":extra STRING" feature is mentioned, but
> without any details; I couldn't understand how to use it in practice
> (it is not used in the tests, either).

I don't know either.

> And I don't recommend believing the commentary too much, either.
> E.g., what it says about &context in several places is contradictory:
>
>    ;;   E.g. (foo &context (major-mode (eql c-mode))) is an arglist specifying
>    ;;   that this method will only be applicable when `major-mode' has value
>    ;;   `c-mode'.
>
> and then:
>
>    ;; - then define a context-rewriter so you can write
>    ;;   "&context (major-mode c-mode)" rather than
>    ;;   "&context (major-mode (derived-mode c-mode))".

Apparently, you can use both forms:

(cl-defmethod bar (&context (major-mode emacs-lisp-mode))
   'elisp)

(cl-defmethod bar (&context (major-mode (eql c-mode)))
   'c)

> and even
>
>    ;; TODO:
>    ;;
>    ;; - A way to dispatch on the context (e.g. the major-mode, some global
>    ;;   variable, you name it).

Yup, this should just be removed.

> which makes you think it isn't even implemented...  Also, there's
> something about derived-mode there, but it's so contrived and devoid
> of examples, that I didn't even put that in the manual.

Good call.

> There were others I was only too happy to forget.

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

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.

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

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

[Dmitry Gutov]

Sorry,

On 01/24/2016 03:45 AM, Dmitry Gutov wrote:

> 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

                            ^ wrote

> by looking at the docstring.

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

[Stefan Monnier]

> (cl-defgeneric foo (a)
>   (:method ((s string)) "stringy!")
>   (:method ((a array)) :four)
>   10)

I implemented this :method thingy simply because CLOS allows it, but I'm
not sure it's worth documenting.

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

Actually, the only "builtin" specializer is t (the generic one).
All other ones are defined via cl-generic-define-generalizer, and we
should improve cl-defmethod's docstring so that it automatically
mentions all the specializers that happen to be currently defined
(i.e. in a dynamic way, just like pcase's docstring dynamically lists
the patterns currently defined via pcase-defmacro).


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>,  22336@debbugs.gnu.org
> Date: Sun, 24 Jan 2016 00:03:21 -0500
> 
> > (cl-defgeneric foo (a)
> >   (:method ((s string)) "stringy!")
> >   (:method ((a array)) :four)
> >   10)
> 
> I implemented this :method thingy simply because CLOS allows it, but I'm
> not sure it's worth documenting.

':method' is in the doc string, which for me was a clear sign it
should be documented.

> > 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. 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).
> 
> Actually, the only "builtin" specializer is t (the generic one).
> All other ones are defined via cl-generic-define-generalizer, and we
> should improve cl-defmethod's docstring so that it automatically
> mentions all the specializers that happen to be currently defined
> (i.e. in a dynamic way, just like pcase's docstring dynamically lists
> the patterns currently defined via pcase-defmacro).

Such dynamically-updated doc string would be very good to have, I
think, but I needed to work with what was there, and of course
couldn't use the kind of intimate knowledge of the implementation that
you have.

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

[Stefan Monnier]

> ':method' is in the doc string, which for me was a clear sign it
> should be documented.

I consider that the docstring should be a "reference" documenting as
much of the supported behavior as possible, whereas the manual should be
more accessible (give context and examples) and less exhaustive.

> Such dynamically-updated doc string would be very good to have, I
> think, but I needed to work with what was there, and of course
> couldn't use the kind of intimate knowledge of the implementation that
> you have.

I definitely understand that, and I thank you for doing this work.


        Stefan