document custom-variable-p

[Drew Adams]

`custom-variable-p' is apparently the predicate for variables that are
`user-variable-p' and are also customizable with Customize. (Some
`user-variable-p' variables are not Customizable; they can be updated
with `set-variable', but they cannot be edited or saved in Customize.)

`user-variable-p' is documented in the Elisp manual, but
`custom-variable-p' is not. The doc string of `user-variable-p'
itemizes the possibilities, but the description of the possibility of
being `custom-variable-p' (item #2) does not mention that predicate
explicitly:

 Return t if VARIABLE is intended to be set and modified by users.
 (The alternative is a variable used internally in a Lisp program.)
 A variable is a user variable if
 (1) the first character of its documentation is `*', or
 (2) it is customizable (its property list contains a non-nil value
     of `standard-value' or `custom-autoload'), or
 (3) it is an alias for another user variable.
 Return nil if VARIABLE is an alias and there is a loop in the
 chain of symbols.

The result is that `custom-variable-p' is mentioned nowhere. Yet Lisp
programs should use `custom-variable-p', not `user-variable-p',
whenever they want to test whether a variable is something that a user
can customize and save.

Suggestion:

a. Update the Elisp manual to explicitly list the possibilities for
`user-variable-p', as is done now in its doc string, and for item #2,
explicitly mention predicate `custom-variable-p'.

b. Reference `custom-variable-p' explicitly also in the doc string of
`user-variable-p'.  We can then shorten the description of item #2
there: no need to describe what `custom-variable-p' means.

c. Update the doc string of `custom-variable-p' to include what is
said now in item #2 for `user-variable-p': the variable has non-nil
`standard-value' or `custom-autoload'.  (The current doc string of
`custom-variable-p' explains nothing.)


In GNU Emacs 22.1.50.1 (i386-mingw-nt5.1.2600)
 of 2007-05-22 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/g/include'