Document and-let* vs. when-let* usage convention

* lisp/subr.el (and-let*): Document and/and-let*
vs. when/when-let* usage convention (some discussion in
bug#73853).
(when-let*): Add cross-reference to and-let*.

(cherry picked from commit 09e05f7ee4de89f5f1dd95aa9498feccfa9a78d6)

diff --git a/lisp/subr.el b/lisp/subr.el
index 86ffa21a1cbf7328b903872f6499e25a2cf06140..c114cc45426c97a431cb6cdab6f2a7e51916cdf6 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2645,14 +2645,22 @@ 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."
+\(SYMBOL SOMETHING) specially.
+
+See also `and-let*'."
   (declare (indent 1) (debug if-let*))
   (list 'if-let* varlist (macroexp-progn body)))
 
 (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."
+are non-nil, then the result is the value of the last binding.
+
+Some Lisp programmers follow the convention that `and' and `and-let*'
+are for forms evaluated for return value, and `when' and `when-let*' are
+for forms evaluated for side-effect with returned values ignored."
+  ;; Document this convention here because it partially explains why we
+  ;; have both `when-let*' and `and-let*'.
   (declare (indent 1) (debug if-let*))
   (let (res)
     (if varlist