From: Richard Stallman <rms@gnu.org>
Date: Wed, 8 Jan 2025 13:40:32 +0000 (-0500)
Subject: subr.el doc clarifications.
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=992d46c9e9ea9c0a31870d62b95f6953f3455a87;p=emacs.git

subr.el doc clarifications.

* subr.el (when-let, when-let*, and-let*): Doc clarifications.
Make `when-let* doc string self-contained.

(cherry picked from commit 67be8db518828bbf8fb3efc5bf87d02e4ce6d8d6)
---

diff --git a/lisp/subr.el b/lisp/subr.el
index 8eab1cce29c..e6c30c8eca5 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2644,8 +2644,11 @@ This is like `if-let' but doesn't handle a VARLIST of the form
 
 (defmacro when-let* (varlist &rest body)
   "Bind variables according to VARLIST and conditionally evaluate BODY.
-This is like `when-let' but doesn't handle a VARLIST of the form
-\(SYMBOL SOMETHING) specially.
+Evaluate each binding in turn, stopping if a binding value is nil.
+If all are non-nil, evaluate the forms in BODY
+and return the value of the last form.
+
+The variable list VARLIST is the same as in `if-let*'.
 
 See also `and-let*'."
   (declare (indent 1) (debug if-let*))
@@ -2653,8 +2656,12 @@ See also `and-let*'."
 
 (defmacro and-let* (varlist &rest body)
   "Bind variables according to VARLIST and conditionally evaluate BODY.
-Like `when-let*', except if BODY is empty and all the bindings
-are non-nil, then the result is the value of the last binding.
+Evaluate each binding in turn, stopping if a binding value is nil.
+If all bindings are non-nil, evaluate the forms in BODY
+and return the value of the last form, or else the last binding value
+if BODY is empty.
+
+Like `when-let*', except for the handling of an empty BODY.
 
 Some Lisp programmers follow the convention that `and' and `and-let*'
 are for forms evaluated for return value, and `when' and `when-let*' are
@@ -2700,7 +2707,8 @@ with an old syntax that accepted only one binding."
 (defmacro when-let (spec &rest body)
   "Bind variables according to SPEC and conditionally evaluate BODY.
 Evaluate each binding in turn, stopping if a binding value is nil.
-If all are non-nil, return the value of the last form in BODY.
+If all are non-nil, evaluate the forms in BODY
+and return the value of the last form.
 
 The variable list SPEC is the same as in `if-let'."
   (declare (indent 1) (debug if-let))