EXPVAL in pcase-defmacro docstrings

[Stefan Monnier]

I think this change is misguided:

- When reading source code, you get things like:

      (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."

  where the EXPVAL comes out of nowhere

- The wording "matches radix-tree leaf EXPVAL" makes it sound like the
  reader is already familiar with EXPVAL and that we know already that
  it's a radix-tree leaf, whereas the pattern will have to check if
  EXPVAL is such a leaf.

- In the pcase docstring, EXPVAL refers to the "toplevel" value, so when
  we say things like

      'VAL             matches if EXPVAL is `equal' to VAL.

  it makes it sound like

      (cons '1 '2)

  will not match against the value (1 . 2) because EXPVAL is (1 . 2) and
  '1 is not `equal` to (1 . 2).

- The "standard" way to describe a pattern is to say things like

      (fumble-tree E1 E2) matches fumble-trees

  E.g.

      _ matches anything
      SYMBOL           matches anything and binds it to SYMBOL.
      (guard BOOLEXP)  matches if BOOLEXP evaluates to non-nil.
      (let PAT EXPR)   matches if EXPR matches PAT.
      (and PAT...)     matches if all the patterns match.
      (or PAT...)      matches if any of the patterns matches.

  While it may occasionally be handy to be able to refer to EXPVAL,
  for example in

      (app FUN PAT)    matches if FUN called on EXPVAL matches PAT.

  I believe the standard terminology is to say "the target" instead of
  EXPVAL.

For example, I think the patch below would improve the doc.


        Stefan


diff --git a/lisp/emacs-lisp/radix-tree.el b/lisp/emacs-lisp/radix-tree.el
index 2491ccea95..6a11977782 100644
--- a/lisp/emacs-lisp/radix-tree.el
+++ b/lisp/emacs-lisp/radix-tree.el
@@ -196,8 +196,8 @@ radix-tree-prefixes
 
 (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."
+    "Pattern which matches a radix-tree leaf.
+The pattern VPAT is matched against the leaf's carried 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/pcase.el b/lisp/emacs-lisp/pcase.el
index fa7b1de8b4..0ba0d75776 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -119,7 +119,7 @@ pcase
 PATTERN matches.  PATTERN can take one of the forms:
 
   _                matches anything.
-  \\='VAL             matches if EXPVAL is `equal' to VAL.
+  \\='VAL             matches objects `equal' to VAL.
   KEYWORD          shorthand for \\='KEYWORD
   INTEGER          shorthand for \\='INTEGER
   STRING           shorthand for \\='STRING