bug#30101: 25.3; defcustom does not clear old :options when reevaluated

[Mauro Aranda <maurooaranda@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 299 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tim Landscheidt <tim@tim-landscheidt.de>
>> Date: Sun, 14 Jan 2018 20:32:19 +0000
>>
>> So this behaviour cannot be changed, but should be document-
>> ed.
>
> Patches to document this will be welcome.
>
> Thanks.

I took a shot at it.  Please review.

[-- Attachment #1.2: Type: text/html, Size: 491 bytes --]

[-- Attachment #2: 0001-Improve-documentation-for-custom-options.patch --]
[-- Type: text/x-patch, Size: 2120 bytes --]

From 2315d1e3cec264ef89daea51772ee348ab187a3e Mon Sep 17 00:00:00 2001
From: Mauro Aranda <maurooaranda@gmail.com>
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