Document that variable binding order is unspecified

* doc/lispref/variables.texi (Local Variables):
* cl.texi (Modify Macros): Document that binding order in 'let' and
'cl-letf' is unspecified.

2 files changed, 17 insertions, 0 deletions

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a2d64815d94..ba31f856369 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -221,6 +221,18 @@ Here is an example of this: @code{z} is bound to the old value of
      @result{} (1 2)
 @end group
 @end example
+
+On the other hand, the order of @emph{bindings} is unspecified: in the
+following example, either 1 or 2 might be printed.
+
+@example
+(let ((x 1)
+      (x 2))
+  (print x))
+@end example
+
+Therefore, avoid binding a variable more than once in a single
+@code{let} form.
 @end defspec
 
 @defspec let* (bindings@dots{}) forms@dots{}
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index c62fa727c10..75a83602fa3 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1179,6 +1179,11 @@ behavior.  (@code{point} and @code{point-marker} are equivalent
 as @code{setf} places; each will accept either an integer or a
 marker as the stored value.)
 
+Like in the case of @code{let}, the @var{value} forms are evaluated in
+the order they appear, but the order of bindings is unspecified.
+Therefore, avoid binding the same @var{place} more than once in a
+single @code{cl-letf} form.
+
 Since generalized variables look like lists, @code{let}'s shorthand
 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
 be ambiguous in @code{cl-letf} and is not allowed.