master 1b30431 2/2: Improve the documentation of :extra in cl-defmethod

[Lars Ingebrigtsen]

branch: master
commit 1b30431c0ec871658423ba080eb6c89df24e7232
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Improve the documentation of :extra in cl-defmethod
    
    * doc/lispref/functions.texi (Generic Functions): Improve
    documentation of :extra (bug#46917).
    
    * lisp/emacs-lisp/cl-generic.el (cl-defmethod): Ditto.
---
 doc/lispref/functions.texi    |  9 +++++----
 lisp/emacs-lisp/cl-generic.el | 10 +++++++---
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 2a9b57f..64883bf 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1181,7 +1181,7 @@ This form defines a method like @code{cl-defmethod} does.
 @end table
 @end defmac
 
-@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] 
&rest [docstring] body
+@defmac cl-defmethod name [extra] [qualifier] arguments [&context (expr 
spec)@dots{}] &rest [docstring] body
 This macro defines a particular implementation for the generic
 function called @var{name}.  The implementation code is given by
 @var{body}.  If present, @var{docstring} is the documentation string
@@ -1267,6 +1267,10 @@ Parent type: @code{array}.
 @item font-object
 @end table
 
+The optional @var{extra} element, expressed as @samp{:extra
+@var{string}}, allows you to add more methods, distinguished by
+@var{string}, for the same specializers and qualifiers.
+
 The optional @var{qualifier} allows combining several applicable
 methods.  If it is not present, the defined method is a @dfn{primary}
 method, responsible for providing the primary implementation of the
@@ -1288,9 +1292,6 @@ This auxiliary method will run @emph{instead} of the 
primary method.
 The most specific of such methods will be run before any other method.
 Such methods normally use @code{cl-call-next-method}, described below,
 to invoke the other auxiliary or primary methods.
-@item :extra @var{string}
-This allows you to add more methods, distinguished by @var{string},
-for the same specializers and qualifiers.
 @end table
 
 Functions defined using @code{cl-defmethod} cannot be made
diff --git a/lisp/emacs-lisp/cl-generic.el b/lisp/emacs-lisp/cl-generic.el
index e78f88e..f5b8c7b 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -455,8 +455,12 @@ all methods of NAME have to use the same set of arguments 
for dispatch.
 Each 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:
+The optional EXTRA element, on the form `:extra STRING', allows
+you to add more methods for the same specializers and qualifiers.
+These are distinguished by STRING.
+
+The optional 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
@@ -473,7 +477,7 @@ method to be applicable.
 The set of acceptable TYPEs (also called \"specializers\") is defined
 \(and can be extended) by the various methods of `cl-generic-generalizers'.
 
-\(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"
+\(fn NAME [EXTRA] [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"
   (declare (doc-string cl--defmethod-doc-pos) (indent defun)
            (debug
             (&define                    ; this means we are defining something