[Emacs-diffs] fix/bug-31311-pcase-doc-squash 7e8227e 2/5: Introduce EXPVAL for pcase, pcase-defmacro docstrings

[Thien-Thi Nguyen]

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

    Introduce EXPVAL for pcase, pcase-defmacro docstrings
    
    Suggested by Drew Adams (Bug#31311).
    
    * lisp/emacs-lisp/pcase.el (pcase): Use EXPVAL in
    docstring to stand for the result of evaluating EXP.
    (pcase-defmacro): Add (fn ...) form in docstring
    that includes [DOC], and the EXPVAL convention.
---
 lisp/emacs-lisp/pcase.el | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 6e8f08e..38e434d 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -108,7 +108,7 @@
 
 ;;;###autoload
 (defmacro pcase (exp &rest cases)
-  "Evaluate EXP and attempt to match it against structural patterns.
+  "Evaluate EXP to get EXPVAL; try passing control to one of CASES.
 CASES is a list of elements of the form (PATTERN CODE...).
 
 A structural PATTERN describes a template that identifies a class
@@ -427,7 +427,11 @@ 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.
+
+By convention, DOC should use \"EXPVAL\" to stand
+for the result of evaluating EXP (first arg to `pcase').
+\n(fn NAME ARGS [DOC] &rest BODY...)"
   (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.