Doc updates for defvar, defconst, and defcustom.

* lisp/custom.el (defcustom): Doc fix; note use of defvar.

* src/eval.c (Fdefvar, Fdefconst): Doc fix; note that the variable is
marked as special.  Also, starting docstrings with * is obsolete.

4 files changed, 43 insertions, 21 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a3b5a4d9486..6ec2cd2f038 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * custom.el (defcustom): Doc fix; note use of defvar.
+
 2012-02-15  Glenn Morris  <rgm@gnu.org>
 
         * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):
diff --git a/lisp/custom.el b/lisp/custom.el
index 2d880d23955..810b78144a4 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -208,7 +208,11 @@ is unbound.  The expression itself is also stored, so that
 Customize can re-evaluate it later to get the standard value.
 DOC is the variable documentation.
 
-The remaining arguments should have the form
+This macro uses `defvar' as a subroutine, which also marks the
+variable as \"special\", so that it is always dynamically bound
+even when `lexical-binding' is t.
+
+The remaining arguments to `defcustom' should have the form
 
    [KEYWORD VALUE]...
 
diff --git a/src/ChangeLog b/src/ChangeLog
index 7893cd68396..4375ffef3d7 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * eval.c (Fdefvar, Fdefconst): Doc fix; note that the variable is
+        marked as special.  Also, starting docstrings with * is obsolete.
+
 2012-02-13  Andreas Schwab  <schwab@linux-m68k.org>
 
         * gnutls.c (emacs_gnutls_write): Fix last change.
diff --git a/src/eval.c b/src/eval.c
index dbd06e7c1b1..344228741cb 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -780,17 +780,15 @@ The return value is BASE-VARIABLE.  */)
 
 DEFUN ("defvar", Fdefvar, Sdefvar, 1, UNEVALLED, 0,
        doc: /* Define SYMBOL as a variable, and return SYMBOL.
-You are not required to define a variable in order to use it,
-but the definition can supply documentation and an initial value
-in a way that tags can recognize.
-
-INITVALUE is evaluated, and used to set SYMBOL, only if SYMBOL's value is void.
-If SYMBOL is buffer-local, its default value is what is set;
- buffer-local values are not affected.
-INITVALUE and DOCSTRING are optional.
-If DOCSTRING starts with *, this variable is identified as a user option.
- This means that M-x set-variable recognizes it.
- See also `user-variable-p'.
+You are not required to define a variable in order to use it, but
+defining it lets you supply an initial value and documentation, which
+can be referred to by the Emacs help facilities and other programming
+tools.  The `defvar' form also declares the variable as \"special\",
+so that it is always dynamically bound even if `lexical-binding' is t.
+
+The optional argument INITVALUE is evaluated, and used to set SYMBOL,
+only if SYMBOL's value is void.  If SYMBOL is buffer-local, its
+default value is what is set; buffer-local values are not affected.
 If INITVALUE is missing, SYMBOL's value is not set.
 
 If SYMBOL has a local binding, then this form affects the local
@@ -799,6 +797,13 @@ load a file defining variables, with this form or with `defconst' or
 `defcustom', you should always load that file _outside_ any bindings
 for these variables.  \(`defconst' and `defcustom' behave similarly in
 this respect.)
+
+The optional argument DOCSTRING is a documentation string for the
+variable.
+
+To define a user option, use `defcustom' instead of `defvar'.
+The function `user-variable-p' also identifies a variable as a user
+option if its DOCSTRING starts with *, but this behavior is obsolete.
 usage: (defvar SYMBOL &optional INITVALUE DOCSTRING)  */)
   (Lisp_Object args)
 {
@@ -873,15 +878,19 @@ usage: (defvar SYMBOL &optional INITVALUE DOCSTRING)  */)
 
 DEFUN ("defconst", Fdefconst, Sdefconst, 2, UNEVALLED, 0,
        doc: /* Define SYMBOL as a constant variable.
-The intent is that neither programs nor users should ever change this value.
-Always sets the value of SYMBOL to the result of evalling INITVALUE.
-If SYMBOL is buffer-local, its default value is what is set;
- buffer-local values are not affected.
-DOCSTRING is optional.
-
-If SYMBOL has a local binding, then this form sets the local binding's
-value.  However, you should normally not make local bindings for
-variables defined with this form.
+This declares that neither programs nor users should ever change the
+value.  This constancy is not actually enforced by Emacs Lisp, but
+SYMBOL is marked as a special variable so that it is never lexically
+bound.
+
+The `defconst' form always sets the value of SYMBOL to the result of
+evalling INITVALUE.  If SYMBOL is buffer-local, its default value is
+what is set; buffer-local values are not affected.  If SYMBOL has a
+local binding, then this form sets the local binding's value.
+However, you should normally not make local bindings for variables
+defined with this form.
+
+The optional DOCSTRING specifies the variable's documentation string.
 usage: (defconst SYMBOL INITVALUE [DOCSTRING])  */)
   (Lisp_Object args)
 {