Re: Replace trivial pcase occurrences in the Emacs sources

[Stefan Monnier]

>> > Doc strings which specify fully the arguments to these macros, including
>> > their semantics, and say what the macros do.  The current doc strings
>> > (at least some of them) for these macros don't do this.
>> I understand this in theory, but I don't know what it means in this
>> concrete case.
> Take a look at, for example, the doc string for pcase-dolist.  In its
> entirety, it's this:

Thanks.  What do you think of the patch below?

I'd rather keep it defined in terms of its differences w.r.t `dolist`,
but if really needed, we could change the doc so it doesn't rely on
`dolist`s own doc at all.

We do have to keep the reference to `pcase` because we don't want to
repeat the definition of what a pcase pattern can look like.


        Stefan


diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 57c2d6c3cb..861c900b21 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -281,7 +281,7 @@ pcase-let*
 (defmacro pcase-let (bindings &rest body)
   "Like `let' but where you can use `pcase' patterns for bindings.
 BODY should be a list of expressions, and BINDINGS should be a list of bindings
-of the form (PAT EXP).
+of the form (PATTERN EXP).
 The macro is expanded and optimized under the assumption that those
 patterns *will* match, so a mismatch may go undetected or may cause
 any kind of error."
@@ -302,7 +302,12 @@ pcase-let
 
 ;;;###autoload
 (defmacro pcase-dolist (spec &rest body)
-  "Like `dolist' but where the binding can be a `pcase' pattern.
+  "Superset of `dolist' where the VAR binding can be a `pcase' PATTERN.
+More specifically `dolist's VAR binding is replaced by a PATTERN
+against which each element of the list is matched.
+As in the case of `pcase-let', PATTERN is matched under the assumption
+that it *will* match.
+
 \n(fn (PATTERN LIST) BODY...)"
   (declare (indent 1) (debug ((pcase-PAT form) body)))
   (if (pcase--trivial-upat-p (car spec))