bug#56974: 29.0.50; Missing documentation for former subr-x macros

[Philip Kaludercic <philipk@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 727 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Date: Thu, 04 Aug 2022 13:06:20 +0000
>> 
>> 
>> As far as I see, if-let, when-let, thread-first, ... were moved from
>> subr-x.el to subr.el last April (b05a103e).  But there appears to be no
>> documentation in (I'd assume) lispref/controls.texi.  My understanding
>> was that these macros were not documented in the Elisp manual as they
>> were just part of subr-x, as the comment in the subr-x header indicates
>> 
>>     ;; Do not document these functions in the lispref.
>>     ;; https://lists.gnu.org/r/emacs-devel/2014-01/msg01006.html
>> 
>> So should they be documented now?
>
> Yes, they should be.

How is this for a start:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-if-let-if-let-when-let-and-and-let.patch --]
[-- Type: text/x-patch, Size: 2777 bytes --]

From 0d4c3f418d5dcdaa2f2f9c93b7e1fd103a310c62 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Fri, 5 Aug 2022 11:18:29 +0200
Subject: [PATCH] Document if-let*, if-let, when-let* and and-let*

* control.texi (Conditionals): Add if-let*, if-let, when-let*
(Combining Conditions): Add and-let*
---
 doc/lispref/control.texi | 47 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index d4520ebdee..e7fd1bb41a 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -294,6 +294,46 @@ Conditionals
 @end group
 @end example
 
+During complex computations that might at any step, one can combine a
+@code{let}-block and some of the previous conditional control
+structures:
+
+@defmac if-let (bindings@dots) then &rest else@dots
+As with @code{let*}, @var{bindings} will consist of
+@code{(@var{symbol} @var{value-form})} entries that are evaluated and
+bound sequentially.  If all @var{value-form} evaluate to
+non-@code{nil} values, then @var{then} is evaluated as were the case
+with a regular @code{let*} expression, with all the variables bound.
+If any @var{value-form} evaluates to @code{nil}, @var{else} is
+evaluated, without any bound variables.
+
+A binding may also optionally drop the @var{symbol}, and simplify to
+@code{(@var{value-form})} if only the test is of interest.
+
+For the sake of backwards compatibility, it is possible to write a
+single binding without a binding list:
+
+@example
+@group
+(if-let* (@var{symbol} (test)) foo bar)
+@equiv{}
+(if-let* ((@var{symbol} (test))) foo bar)
+@end group
+@end example
+@end defmac
+
+@defmac if-let* (bindings@dots) then &rest else
+@code{if-let*} is mostly equivalent to @code{if-let}, with the
+exception that the legacy @code{(if (@var{var} (test)) foo bar)}
+syntax is not permitted.
+@end defmac
+
+@defmac when-let (bindings@dots) &rest body
+As with @code{when}, if one is only interested in the case where all
+@var{bindings} are non-nil.  Otherwise @var{bindings} are interpreted
+just as they are by @code{if-let*}.
+@end defmac
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions
@@ -428,6 +468,13 @@ Combining Conditions
 Note that in contrast to @code{or}, both arguments are always evaluated.
 @end defun
 
+@defmac and-let* (bindings@dots) &rest body
+A combination of @var{let*} and @var{and}, analogous to
+@code{when-let*}.  If all @var{bindings} are non-@code{nil} and
+@var{body} is @code{nil}, then the result of the @code{and-let*} form
+will be the last value bound in @var{bindings}.
+@end defmac
+
 @node Pattern-Matching Conditional
 @section Pattern-Matching Conditional
 @cindex pcase
-- 
2.37.1