emacs-29 9b32bc134c4: Improve documentation of 'defcustom's :set keyword

[Eli Zaretskii]

branch: emacs-29
commit 9b32bc134c4b4d8928df1bdc39907d9b1d6c73b5
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'defcustom's :set keyword
    
    * lisp/custom.el (defcustom):
    * doc/lispref/customize.texi (Variable Definitions): Improve the
    documentation of the :set keyword in 'defcustom'.
---
 doc/lispref/customize.texi | 9 ++++++++-
 lisp/custom.el             | 4 +++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 308145def55..6015c134d21 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -378,8 +378,15 @@ the option as a Lisp variable); preferably, though, it 
should not
 modify its value argument destructively.  The default for
 @var{setfunction} is @code{set-default-toplevel-value}.
 
+If defined, @var{setfunction} will also be called when evaluating a
+@code{defcustom} form with @kbd{C-M-x} in Emacs Lisp mode and when the
+@var{option}'s value is changed via the @code{setopt} macro
+(@pxref{Setting Variables, setopt}).
+
 If you specify this keyword, the variable's documentation string
-should describe how to do the same job in hand-written Lisp code.
+should describe how to do the same job in hand-written Lisp code,
+either by invoking @var{setfunction} directly or by using
+@code{setopt}.
 
 @item :get @var{getfunction}
 @kindex get@r{, @code{defcustom} keyword}
diff --git a/lisp/custom.el b/lisp/custom.el
index 0522bdd447b..df6db181615 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -280,7 +280,9 @@ The following keywords are meaningful:
        when using the Customize user interface.  It takes two arguments,
        the symbol to set and the value to give it.  The function should
        not modify its value argument destructively.  The default choice
-       of function is `set-default-toplevel-value'.
+       of function is `set-default-toplevel-value'.  If this keyword is
+       defined, modifying the value of SYMBOL via `setopt' will call the
+       function specified by VALUE to install the new value.
 :get   VALUE should be a function to extract the value of symbol.
        The function takes one argument, a symbol, and should return
        the current value for that symbol.  The default choice of function