Backport some docstring updates, warn about upcoming obsolescence

Try to save people some time if they're developing on Emacs 30.x.

Do not merge to master.

* lisp/subr.el (if-let*, when-let*, if-let, when-let): Move
docstring text around so that if-let* and when-let* descriptions
no longer refer to if-let and when-let.  Note that if-let and
when-let will be marked obsolete, and recommend if-let*,
when-let* and and-let* for new code.

diff --git a/lisp/subr.el b/lisp/subr.el
index 0acc24042f8e12f2bb07928f910ac859f1485f6f..b849d8d1b162eca2be4f9e6cf07ac7454f1e848b 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2625,8 +2625,17 @@ Affects only hooks run in the current buffer."
 
 (defmacro if-let* (varlist then &rest else)
   "Bind variables according to VARLIST and evaluate THEN or ELSE.
-This is like `if-let' but doesn't handle a VARLIST of the form
-\(SYMBOL SOMETHING) specially."
+Evaluate each binding in turn, as in `let*', stopping if a
+binding value is nil.  If all are non-nil return the value of
+THEN, otherwise the value of the last form in ELSE, or nil if
+there are none.
+
+Each element of VARLIST is a list (SYMBOL VALUEFORM) that binds
+SYMBOL to the value of VALUEFORM.  An element can additionally be
+of the form (VALUEFORM), which is evaluated and checked for nil;
+i.e. SYMBOL can be omitted if only the test result is of
+interest.  It can also be of the form SYMBOL, then the binding of
+SYMBOL is checked for nil."
   (declare (indent 2)
            (debug ((&rest [&or symbolp (symbolp form) (form)])
                    body)))
@@ -2639,8 +2648,10 @@ 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, return the value of the last form in BODY.
+
+The variable list VARLIST is the same as in `if-let*'.
 
 See also `and-let*'."
   (declare (indent 1) (debug if-let*))
@@ -2667,21 +2678,13 @@ for forms evaluated for side-effect with returned values ignored."
 
 (defmacro if-let (spec then &rest else)
   "Bind variables according to SPEC and evaluate THEN or ELSE.
-Evaluate each binding in turn, as in `let*', stopping if a
-binding value is nil.  If all are non-nil return the value of
-THEN, otherwise the value of the last form in ELSE, or nil if
-there are none.
+This is like `if-let*' except, as a special case, interpret a SPEC of
+the form \(SYMBOL SOMETHING) like \((SYMBOL SOMETHING)).  This exists
+for backward compatibility with an old syntax that accepted only one
+binding.
 
-Each element of SPEC is a list (SYMBOL VALUEFORM) that binds
-SYMBOL to the value of VALUEFORM.  An element can additionally be
-of the form (VALUEFORM), which is evaluated and checked for nil;
-i.e. SYMBOL can be omitted if only the test result is of
-interest.  It can also be of the form SYMBOL, then the binding of
-SYMBOL is checked for nil.
-
-As a special case, interprets a SPEC of the form \(SYMBOL SOMETHING)
-like \((SYMBOL SOMETHING)).  This exists for backward compatibility
-with an old syntax that accepted only one binding."
+This macro will be marked obsolete in Emacs 31.1; prefer `if-let*' in
+new code."
   (declare (indent 2)
            (debug ([&or (symbolp form)  ; must be first, Bug#48489
                         (&rest [&or symbolp (symbolp form) (form)])]
@@ -2697,7 +2700,10 @@ with an old syntax that accepted only one binding."
 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.
 
-The variable list SPEC is the same as in `if-let'."
+The variable list SPEC is the same as in `if-let'.
+
+This macro will be marked obsolete in Emacs 31.1; prefer `when-let*' and
+`and-let*' in new code."
   (declare (indent 1) (debug if-let))
   (list 'if-let spec (macroexp-progn body)))