Commit c3a70e2b authored by Chong Yidong's avatar Chong Yidong

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.
parent 9f26dc24
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):
......
......@@ -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]...
......
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.
......
......@@ -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)
{
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment