mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-01 09:51:22 -08:00
Code Issues Projects Releases Wiki Activity

Doc updates for defvar, defconst, and defcustom.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2012-02-15 12:00:34 +08:00
parent 9f26dc2432
commit c3a70e2b95
4 changed files with 41 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

4
lisp/ChangeLog
View file

@ -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> 2012-02-15 Glenn Morris <rgm@gnu.org>
* mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type): * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):

6
lisp/custom.el
View file

@ -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. Customize can re-evaluate it later to get the standard value.
DOC is the variable documentation. 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]... [KEYWORD VALUE]...

5
src/ChangeLog
View file

@ -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> 2012-02-13 Andreas Schwab <schwab@linux-m68k.org>
* gnutls.c (emacs_gnutls_write): Fix last change. * gnutls.c (emacs_gnutls_write): Fix last change.

45
src/eval.c
View file

@ -780,17 +780,15 @@ The return value is BASE-VARIABLE. */)
DEFUN ("defvar", Fdefvar, Sdefvar, 1, UNEVALLED, 0, DEFUN ("defvar", Fdefvar, Sdefvar, 1, UNEVALLED, 0,
doc: /* Define SYMBOL as a variable, and return SYMBOL. doc: /* Define SYMBOL as a variable, and return SYMBOL.
You are not required to define a variable in order to use it, You are not required to define a variable in order to use it, but
but the definition can supply documentation and an initial value defining it lets you supply an initial value and documentation, which
in a way that tags can recognize. 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. The optional argument INITVALUE is evaluated, and used to set SYMBOL,
If SYMBOL is buffer-local, its default value is what is set; only if SYMBOL's value is void. If SYMBOL is buffer-local, its
buffer-local values are not affected. 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'.
If INITVALUE is missing, SYMBOL's value is not set. If INITVALUE is missing, SYMBOL's value is not set.
If SYMBOL has a local binding, then this form affects the local 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 `defcustom', you should always load that file _outside_ any bindings
for these variables. \(`defconst' and `defcustom' behave similarly in for these variables. \(`defconst' and `defcustom' behave similarly in
this respect.) 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) */) usage: (defvar SYMBOL &optional INITVALUE DOCSTRING) */)
(Lisp_Object args) (Lisp_Object args)
{ {
@ -873,15 +878,19 @@ usage: (defvar SYMBOL &optional INITVALUE DOCSTRING) */)
DEFUN ("defconst", Fdefconst, Sdefconst, 2, UNEVALLED, 0, DEFUN ("defconst", Fdefconst, Sdefconst, 2, UNEVALLED, 0,
doc: /* Define SYMBOL as a constant variable. doc: /* Define SYMBOL as a constant variable.
The intent is that neither programs nor users should ever change this value. This declares that neither programs nor users should ever change the
Always sets the value of SYMBOL to the result of evalling INITVALUE. value. This constancy is not actually enforced by Emacs Lisp, but
If SYMBOL is buffer-local, its default value is what is set; SYMBOL is marked as a special variable so that it is never lexically
buffer-local values are not affected. bound.
DOCSTRING is optional.
If SYMBOL has a local binding, then this form sets the local binding's The `defconst' form always sets the value of SYMBOL to the result of
value. However, you should normally not make local bindings for evalling INITVALUE. If SYMBOL is buffer-local, its default value is
variables defined with this form. 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]) */) usage: (defconst SYMBOL INITVALUE [DOCSTRING]) */)
(Lisp_Object args) (Lisp_Object args)
{ {