[Emacs-diffs] master 94b5220: Clarify manual section on &context specializer for methods

[Eric Abrahamsen]

branch: master
commit 94b52207cf0bd25d3e8052b01bda945e8718bd12
Author: Eric Abrahamsen <address@hidden>
Commit: Eric Abrahamsen <address@hidden>

    Clarify manual section on &context specializer for methods
    
    * doc/lispref/functions.texi (Generic Functions): Provide a little
      more information on how they work.
---
 doc/lispref/functions.texi | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 466a12f..d84f09d 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1225,7 +1225,7 @@ This form defines a method like @code{cl-defmethod} does.
 @end table
 @end defmac
 
address@hidden cl-defmethod name [qualifier] arguments &rest [docstring] body
address@hidden cl-defmethod name [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
@@ -1252,15 +1252,20 @@ defined with @code{cl-defstruct} (@pxref{Structures,,, 
cl, Common Lisp
 Extensions for GNU Emacs Lisp}), or of one of its parent classes.
 @end table
 
-Alternatively, the argument specializer can be of the form
address@hidden&context (@var{expr} @var{spec})}, in which case the value of
address@hidden must be compatible with the specializer provided by
address@hidden; @var{spec} can be any of the forms described above.  In
-other words, this form of specializer uses the value of @var{expr}
-instead of arguments for the decision whether the method is
-applicable.  For example, @code{&context (overwrite-mode (eql t))}
-will make the method compatible only when @code{overwrite-mode} is
-turned on.
+Method definitions can make use of a new argument-list keyword,
address@hidden&context}, which introduces extra specializers that test the
+environment at the time the method is run.  This keyword should appear
+after the list of required arguments, but before any @code{&rest} or
address@hidden&optional} keywords.  The @code{&context} specializers look much
+like regular argument specializers---(@var{expr} @var{spec})---except
+that @var{expr} is an expression to be evaluated in the current
+context, and the @var{spec} is a value to compare against.  For
+example, @code{&context (overwrite-mode (eql t))} will make the method
+applicable only when @code{overwrite-mode} is turned on.  The
address@hidden&context} keyword can be followed by any number of context
+specializers.  Because the context specializers are not part of the
+generic function's argument signature, they may be omitted in methods
+that don't require them.
 
 The type specializer, @code{(@var{arg} @var{type})}, can specify one
 of the @dfn{system types} in the following list.  When a parent type