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.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a3b5a4d9486952194ac95d853f5ae08108ee5ea7..6ec2cd2f038db177fad1cc4afd4489fa4e94324e 100644 (file)
--- 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 2d880d23955ab9a5bc8549e0f9eaa4ab2ea4d405..810b78144a4614acbc84f8ee38b6f5b2afced55c 100644 (file)
--- 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 7893cd68396f498062059f3e1bbfd7a6238b98c7..4375ffef3d7a56dbce0f37cf4d3a1cfb24c993ab 100644 (file)
--- 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 dbd06e7c1b1ae9dde15cf314589f47cc9f5095b1..344228741cbd6d084b109e092892259e4f6d8cd3 100644 (file)
--- 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)
 {