From c3a70e2b95e4cf41b1a671f7d721f0ba4aaff679 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 15 Feb 2012 12:00:34 +0800 Subject: [PATCH] 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. --- lisp/ChangeLog | 4 ++++ lisp/custom.el | 6 +++++- src/ChangeLog | 5 +++++ src/eval.c | 49 +++++++++++++++++++++++++++++-------------------- 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 + + * custom.el (defcustom): Doc fix; note use of defvar. + 2012-02-15 Glenn Morris * 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 + + * 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 * 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) { -- 2.39.2