Update special conditionals documentation

* doc/lispref/control.texi (Conditionals): Document if-let* and
when-let*, not if-let and when-let.  Document and-let*.

1 files changed, 18 insertions, 7 deletions

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 58063ecf8db..5ccc8462c9e 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -313,30 +313,41 @@ to make this easier and more readable.  The above can be written the
 following way instead:
 
 @example
-(when-let ((result1 (do-computation))
-           (result2 (do-more result1)))
+(when-let* ((result1 (do-computation))
+            (result2 (do-more result1)))
   (do-something result2))
 @end example
 
 There's a number of variations on this theme, and they're briefly
 described below.
 
-@defmac if-let spec then-form else-forms...
-Evaluate each binding in @var{spec} in turn, like in @code{let*}
+@defmac if-let* varlist then-form else-forms...
+Evaluate each binding in @var{varlist} in turn, like in @code{let*}
 (@pxref{Local Variables}), stopping if a binding value is @code{nil}.
 If all are non-@code{nil}, return the value of @var{then-form},
 otherwise the last form in @var{else-forms}.
 @end defmac
 
-@defmac when-let spec then-forms...
-Like @code{if-let}, but without @var{else-forms}.
+@defmac when-let* varlist then-forms...
+Like @code{if-let*}, but without @var{else-forms}.
+@end defmac
+
+@defmac and-let* varlist then-forms...
+Like @code{when-let*}, but in addition, if there are no
+@var{then-forms} and all the bindings evaluate to non-nil, return the
+value of the last binding.
 @end defmac
 
 @defmac while-let spec then-forms...
-Like @code{when-let}, but repeat until a binding in @var{spec} is
+Like @code{when-let*}, but repeat until a binding in @var{spec} is
 @code{nil}.  The return value is always @code{nil}.
 @end defmac
 
+Some Lisp programmers follow the convention that @code{and} and
+@code{and-let*} are for forms evaluated for return value, and
+@code{when} and @code{when-let*} are for forms evaluated for side-effect
+with returned values ignored.
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions