Improved `eval` documentation

Prompted by Michael Heerdegen.

* src/eval.c (Feval):
* doc/lispref/eval.texi (Eval):
Be more precise about the LEXICAL argument.

1 files changed, 7 insertions, 3 deletions

diff --git a/src/eval.c b/src/eval.c
index 9268b65aa85..f5397e9fb72 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -2364,9 +2364,13 @@ static Lisp_Object list_of_t;  /* Never-modified constant containing (t).  */
 
 DEFUN ("eval", Feval, Seval, 1, 2, 0,
        doc: /* Evaluate FORM and return its value.
-If LEXICAL is t, evaluate using lexical scoping.
-LEXICAL can also be an actual lexical environment, in the form of an
-alist mapping symbols to their value.  */)
+If LEXICAL is `t', evaluate using lexical binding by default.
+This is the recommended value.
+
+If absent or `nil', use dynamic scoping only.
+
+LEXICAL can also represent an actual lexical environment; see the Info
+node `(elisp)Eval' for details.  */)
   (Lisp_Object form, Lisp_Object lexical)
 {
   specpdl_ref count = SPECPDL_INDEX ();