[Emacs-diffs] fix/bug-31311-pcase-doc 75ed6d2 05/16: use ‘EXPVAL’ in ‘pcase-defmacro’ et al docstrings

[Thien-Thi Nguyen]

branch: fix/bug-31311-pcase-doc
commit 75ed6d20bed56fdc022d58a1dd9c7726269cae53
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>

    use ‘EXPVAL’ in ‘pcase-defmacro’ et al docstrings
    
    Say "for documentation consistency" in both docstring and manual.
    Two instances where docstrings were not changed: ‘seq’ and ‘map’.
    For ‘seq’, EXPVAL was effectively expressed as ‘SEQUENCE’.
    For ‘map’, EXPVAL was effectively expressed as ‘map’.
---
 doc/lispref/control.texi      | 6 +++++-
 lisp/emacs-lisp/cl-macs.el    | 8 ++++----
 lisp/emacs-lisp/eieio.el      | 8 ++++----
 lisp/emacs-lisp/pcase.el      | 7 +++++--
 lisp/emacs-lisp/radix-tree.el | 2 ++
 lisp/emacs-lisp/rx.el         | 2 +-
 6 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index eb0728e..e0780ab 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -595,12 +595,16 @@ evaluation results:
 Additional U-patterns can be defined using the @code{pcase-defmacro}
 macro.
 
address@hidden pcase-defmacro name args &rest body
address@hidden pcase-defmacro name args &rest [docstring] body
 Define a new kind of U-pattern for @code{pcase}.  The new U-pattern will
 be invoked as @code{(@var{name} @var{actual-args})}.  The @var{body}
 should describe how to rewrite the U-pattern @var{name} into some other
 U-pattern.  The rewriting will be the result of evaluating @var{body}
 in an environment where @var{args} are bound to @var{actual-args}.
+
+For documentation consistency, use @code{EXPVAL}
+in @var{docstring} to stand for the result of
+evaluating @var{expression} (first arg to `pcase').
 @end defmac
 
 @node Combining Conditions
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 971f4f9..9c47cea 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2887,10 +2887,10 @@ non-nil value, that slot cannot be set via `setf'.
 
 ;;;###autoload
 (pcase-defmacro cl-struct (type &rest fields)
-  "Pcase patterns to match cl-structs.
-Elements of FIELDS can be of the form (NAME PAT) in which case the contents of
-field NAME is matched against PAT, or they can be of the form NAME which
-is a shorthand for (NAME NAME)."
+  "Pcase patterns that match cl-struct EXPVAL of type TYPE.
+Elements of FIELDS can be of the form (NAME PAT) in which case the
+contents of field NAME is matched against PAT, or they can be of
+the form NAME which is a shorthand for (NAME NAME)."
   (declare (debug (sexp &rest [&or (sexp pcase-PAT) sexp])))
   `(and (pred (pcase--flip cl-typep ',type))
         ,@(mapcar
diff --git a/lisp/emacs-lisp/eieio.el b/lisp/emacs-lisp/eieio.el
index 78275ac..b95f748 100644
--- a/lisp/emacs-lisp/eieio.el
+++ b/lisp/emacs-lisp/eieio.el
@@ -346,10 +346,10 @@ variable name of the same name as the slot."
                  index))))
 
 (pcase-defmacro eieio (&rest fields)
-  "Pcase patterns to match EIEIO objects.
-Elements of FIELDS can be of the form (NAME PAT) in which case the contents of
-field NAME is matched against PAT, or they can be of the form NAME which
-is a shorthand for (NAME NAME)."
+  "Pcase patterns that match EIEIO object EXPVAL.
+Elements of FIELDS can be of the form (NAME PAT) in which case the
+contents of field NAME is matched against PAT, or they can be of
+ the form NAME which is a shorthand for (NAME NAME)."
   (declare (debug (&rest [&or (sexp pcase-PAT) sexp])))
   (let ((is (make-symbol "table")))
     ;; FIXME: This generates a horrendous mess of redundant let bindings.
diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 97d503a..a0ebec1 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -419,7 +419,10 @@ any kind of error."
 (defmacro pcase-defmacro (name args &rest body)
   "Define a new kind of pcase PATTERN, by macro expansion.
 Patterns of the form (NAME ...) will be expanded according
-to this macro."
+to this macro.
+
+For documentation consistency, use \"EXPVAL\" in the docstring
+to stand for the result of evaluating EXP (first arg to `pcase')."
   (declare (indent 2) (debug defun) (doc-string 3))
   ;; Add the function via `fsym', so that an autoload cookie placed
   ;; on a pcase-defmacro will cause the macro to be loaded on demand.
@@ -920,7 +923,7 @@ QPAT can take the following forms:
   [QPAT1 QPAT2..QPATn]  matches a vector of length n and QPAT1..QPATn match
                            its 0..(n-1)th elements, respectively.
   ,PAT                  matches if the pcase pattern PAT matches.
-  SYMBOL                matches if the object is `equal' to SYMBOL.
+  SYMBOL                matches if EXPVAL is `equal' to SYMBOL.
   KEYWORD               likewise for KEYWORD.
   INTEGER               likewise for INTEGER.
   STRING                likewise for STRING."
diff --git a/lisp/emacs-lisp/radix-tree.el b/lisp/emacs-lisp/radix-tree.el
index 8946560..d76bf02 100644
--- a/lisp/emacs-lisp/radix-tree.el
+++ b/lisp/emacs-lisp/radix-tree.el
@@ -196,6 +196,8 @@ If not found, return nil."
 
 (eval-and-compile
   (pcase-defmacro radix-tree-leaf (vpat)
+    "Build a `pcase' pattern that matches radix-tree leaf EXPVAL.
+VPAT is a `pcase' pattern to extract the value."
     ;; FIXME: We'd like to use a negative pattern (not consp), but pcase
     ;; doesn't support it.  Using `atom' works but generates sub-optimal code.
     `(or `(t . ,,vpat) (and (pred atom) ,vpat))))
diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
index c4f6d4f..302ee23 100644
--- a/lisp/emacs-lisp/rx.el
+++ b/lisp/emacs-lisp/rx.el
@@ -1177,7 +1177,7 @@ enclosed in `(and ...)'.
 (pcase-defmacro rx (&rest regexps)
   "Build a `pcase' pattern matching `rx' regexps.
 The REGEXPS are interpreted as by `rx'.  The pattern matches if
-the regular expression so constructed matches the object, as if
+the regular expression so constructed matches EXPVAL, as if
 by `string-match'.
 
 In addition to the usual `rx' constructs, REGEXPS can contain the