[Emacs-diffs] /srv/bzr/emacs/trunk r107288: Doc updates for defvar, defconst, and defcustom.

[Chong Yidong]

------------------------------------------------------------
revno: 107288
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-15 12:00:34 +0800
message:
  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.
modified:
  lisp/ChangeLog
  lisp/custom.el
  src/ChangeLog
  src/eval.c

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-15 03:15:26 +0000
+++ b/lisp/ChangeLog    2012-02-15 04:00:34 +0000
@@ -1,3 +1,7 @@
+2012-02-15  Chong Yidong  <address@hidden>
+
+       * custom.el (defcustom): Doc fix; note use of defvar.
+
 2012-02-15  Glenn Morris  <address@hidden>
 
        * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):

=== modified file 'lisp/custom.el'
--- a/lisp/custom.el    2012-02-06 12:48:07 +0000
+++ b/lisp/custom.el    2012-02-15 04:00:34 +0000
@@ -208,7 +208,11 @@
 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]...
 

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-02-13 20:39:46 +0000
+++ b/src/ChangeLog     2012-02-15 04:00:34 +0000
@@ -1,3 +1,8 @@
+2012-02-15  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * gnutls.c (emacs_gnutls_write): Fix last change.

=== modified file 'src/eval.c'
--- a/src/eval.c        2012-01-25 05:48:11 +0000
+++ b/src/eval.c        2012-02-15 04:00:34 +0000
@@ -780,17 +780,15 @@
 
 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.
+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.
 
-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'.
+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 @@
 `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 @@
 
 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)
 {