From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Sat, 22 Aug 2020 15:57:35 +0000 (+0200)
Subject: Clarify inline-letevals in the manual
X-Git-Tag: emacs-28.0.90~6456
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4102fe1e91e46fb2fde9ac2f8d279a942d0a6e6f;p=emacs.git

Clarify inline-letevals in the manual

* doc/lispref/functions.texi (Inline Functions): Try to clarify
what inline-letevals really does, and how it differs from `let'
(bug#31052).
---

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 2898cb4d2b4..26b212d05eb 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2163,15 +2163,24 @@ the backquote (@pxref{Backquote}), but quotes code and accepts only
 @end defmac
 
 @defmac inline-letevals (bindings@dots{}) body@dots{}
-This is similar to @code{let} (@pxref{Local Variables}): it sets up
-local variables as specified by @var{bindings}, and then evaluates
-@var{body} with those bindings in effect.  Each element of
-@var{bindings} should be either a symbol or a list of the form
-@w{@code{(@var{var} @var{expr})}}; the result is to evaluate
-@var{expr} and bind @var{var} to the result.  The tail of
-@var{bindings} can be either @code{nil} or a symbol which should hold
-a list of arguments, in which case each argument is evaluated, and the
-symbol is bound to the resulting list.
+This provides a convenient way to ensure that the arguments to an
+inlined function are evaluated exactly once, as well as to create
+local variables.
+
+It's similar to @code{let} (@pxref{Local Variables}): It sets up local
+variables as specified by @var{bindings}, and then evaluates
+@var{body} with those bindings in effect.
+
+Each element of @var{bindings} should be either a symbol or a list of
+the form @w{@code{(@var{var} @var{expr})}}; the result is to evaluate
+@var{expr} and bind @var{var} to the result.  However, when an element
+of @var{bindings} is just a symbol @var{var}, the result of evaluating
+@var{var} is re-bound to @var{var} (which is quite different from the
+way @code{let} works).
+
+The tail of @var{bindings} can be either @code{nil} or a symbol which
+should hold a list of arguments, in which case each argument is
+evaluated, and the symbol is bound to the resulting list.
 @end defmac
 
 @defmac inline-const-p expression