From 09e05f7ee4de89f5f1dd95aa9498feccfa9a78d6 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Wed, 23 Oct 2024 09:07:06 +0800 Subject: [PATCH] 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*. --- lisp/subr.el | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/lisp/subr.el b/lisp/subr.el index 28ba30f584e..d1b2a1efe6e 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -2640,14 +2640,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