From 2315d1e3cec264ef89daea51772ee348ab187a3e Mon Sep 17 00:00:00 2001 From: Mauro Aranda Date: Sat, 29 Aug 2020 12:04:27 -0300 Subject: [PATCH] Improve documentation for custom :options * doc/lispref/customize.texi (Defining Customization Variables): Mention that re-evaluating a defcustom form doesn't reset custom options. (Bug#30101) * lisp/custom.el (custom-add-option): Mention the plist case in the docstring. --- doc/lispref/customize.texi | 6 ++++++ lisp/custom.el | 9 +++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 2a72276bc5..ee94c5e54e 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -479,6 +479,12 @@ Variable Definitions 'my-lisp-mode-initialization) @end example +Re-evaluating a @code{defcustom} form of an already defined user +option does not clear the reasonable values added by previous +evaluations, or by calls to @code{custom-add-frequent-value}. This +way, Lisp programs can add reasonable values for user options not yet +defined. + @defun custom-add-frequent-value symbol value For the customization option @var{symbol}, add @var{value} to the list of reasonable values. diff --git a/lisp/custom.el b/lisp/custom.el index 7581457ce8..8c09fa8ed0 100644 --- a/lisp/custom.el +++ b/lisp/custom.el @@ -578,9 +578,14 @@ custom-add-dependencies (defun custom-add-option (symbol option) "To the variable SYMBOL add OPTION. +Custom then presents OPTION to the user as a suggested member +for the value of SYMBOL. + If SYMBOL's custom type is a hook, OPTION should be a hook member. -If SYMBOL's custom type is an alist, OPTION specifies a symbol -to offer to the user as a possible key in the alist. +If SYMBOL's custom type is an alist, OPTION specifies a possible key +in the alist. +Similarly, if SYMBOL's custom type is a plist, OPTION specifies +a possible name in the plist. For other custom types, this has no effect." (let ((options (get symbol 'custom-options))) (unless (member option options) -- 2.28.0