Use EXPVAL in docstrings of patterns defined using pcase-defmacro

Suggested by Drew Adams (Bug#31311).

* lisp/emacs-lisp/cl-macs.el (cl-struct): ...here.
* lisp/emacs-lisp/eieio.el (eieio): Likewise.
* lisp/emacs-lisp/radix-tree.el (radix-tree-leaf): Likewise.
* lisp/emacs-lisp/rx.el (rx): Likewise.

diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 971f4f926bd24c7641e8cf9ea297656166c95840..9c47ceae18ee702f10ded3bb7d0612ed3eaca5a4 100644 (file)
--- 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 78275acd9c2cdbd525c1abd3b19f4d3f346acb70..b95f7486f7667049dd27d7ba73827394e6b2d8a2 100644 (file)
--- 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/radix-tree.el b/lisp/emacs-lisp/radix-tree.el
index 8946560d3bafdfcba8f711f3916d8d4ed05b4193..d76bf024d0a6baf5587351558d72f30476f4531f 100644 (file)
--- 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 c4f6d4f70ea3413d7213f165a9bd0ef309764e3b..302ee23db6a9ae6e0f01e156f8a0579f2811b433 100644 (file)
--- 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