Clarify that 'pcase-lambda' only destructs

* lisp/emacs-lisp/pcase.el (pcase-lambda): Copy notice from
'pcase-let', indicating that pcase-lambda won't pattern match
like 'pcase', but just try to destruct with uncertain side
effects if this fails. (Bug#71503)

(cherry picked from commit 0756f3085ea948c945e309e2ce347fc5ab836574)

diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 5a7f3995311e37a28aa41e18c83dc4573cae85d8..fd6b0c8db5cb7cf39bee8f70778e87d662743519 100644 (file)
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -241,9 +241,14 @@ not signal an error."
 ;;;###autoload
 (defmacro pcase-lambda (lambda-list &rest body)
   "Like `lambda' but allow each argument to be a pattern.
-I.e. accepts the usual &optional and &rest keywords, but every
-formal argument can be any pattern accepted by `pcase' (a mere
-variable name being but a special case of it)."
+I.e. accepts the usual &optional and &rest keywords, but every formal
+argument can be any pattern destructed by `pcase-let' (a mere variable
+name being but a special case of it).
+
+Each argument should match its respective pattern in the parameter
+list (i.e. be of a compatible structure); a mismatch may signal an error
+or may go undetected, binding arguments to arbitrary values, such as
+nil."
   (declare (doc-string 2) (indent defun)
            (debug (&define (&rest pcase-PAT) lambda-doc def-body)))
   (let* ((bindings ())