Document `letrec'

* doc/lispref/variables.texi (Local Variables): Document letrec
(bug#21048).

* lisp/subr.el (letrec): Expand the doc string slightly.

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index b49874f9eb26a0ad5d874d877a92b2d7d976c692..8d6cc293800f1a3503d7975d1ab6d81f9b7afc7d 100644 (file)
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -265,6 +265,15 @@ Compare the following example with the example above for @code{let}.
      @result{} (1 1)
 @end group
 @end example
+@end defspec
+
+@defspec letrec (bindings@dots{}) forms@dots{}
+This special form is like @code{let}, but all the variables are bound
+before any of the local values are computed.  The values are then
+assigned to the locally bound variables.  This is only useful when
+lexical binding is in effect, and you want to create closures that
+refer to bindings that would otherwise not yet be in effect when using
+@code{let}.
 @end defspec
 
   Here is a complete list of the other facilities that create local

diff --git a/lisp/subr.el b/lisp/subr.el
index b0a9a8395833b2d36c15015cbf6a748b9fe918d1..e361b8324f7b69fd5c174a069dba68c6fe99a3e6 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1739,7 +1739,9 @@ the hook's buffer-local value rather than its default value."
 The value of the last form in BODY is returned.
 Each element of BINDERS is a list (SYMBOL VALUEFORM) which binds
 SYMBOL to the value of VALUEFORM.
-All symbols are bound before the VALUEFORMs are evalled."
+
+The main difference between this macro and `let'/`let*' is that
+all symbols are bound before any of the VALUEFORMs are evalled."
   ;; Only useful in lexical-binding mode.
   ;; As a special-form, we could implement it more efficiently (and cleanly,
   ;; making the vars actually unbound during evaluation of the binders).