emacs-31 1b500ce5a5c: Fix documentation of ':set' function in 'defcustom'

branch: emacs-31
commit 1b500ce5a5c7849cd1a1a9d30a2ec76426c9e2e5
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    Fix documentation of ':set' function in 'defcustom'
    
    * etc/NEWS: Document the change in signature of ':set'.
    * lisp/custom.el (defcustom): Doc fix.  (Bug#81547)
---
 etc/NEWS       | 18 +++++++++++++-----
 lisp/custom.el | 14 +++++++++-----
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index d71204b6be0..353aaf27289 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3576,6 +3576,19 @@ can use this command as a shortcut to jump to the first actionable
 button or field (for instance an on/off button for boolean options, or a
 text field for other values).
 
++++
+*** The ':set' function should accept an optional argument BUFFER-LOCAL.
+This is the third argument, in addition to SYMBOL and VALUE.  If that
+argument's value is 'buffer-local', the ':set' function should use
+'set-local' to set the value of its SYMBOL argument locally in the
+current buffer.  This is used by 'setopt-local', which will signal an
+error if this optional argument is not supported by the ':set' function.
+
++++
+** The 'defcustom' ':local' keyword can now be 'permanent-only'.
+This means that the variable's 'permanent-local' property is set to t,
+without marking it as automatically buffer-local.
+
 ** Pulse
 
 ---
@@ -4526,11 +4539,6 @@ This function gets all the text within a DOM node recursively, returning
 it as a concatenated string.  It replaces the now-obsolete functions
 'dom-text' and 'dom-texts'.
 
-+++
-** The 'defcustom' ':local' keyword can now be 'permanent-only'.
-This means that the variable's 'permanent-local' property is set to t,
-without marking it as automatically buffer-local.
-
 ---
 ** The obsolete face attribute ':reverse-video' has been removed.
 Use ':inverse-video' instead.
diff --git a/lisp/custom.el b/lisp/custom.el
index 59b15032de1..a6bf4f87491 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -300,11 +300,15 @@ The following keywords are meaningful:
 	given in the `defcustom' call.  The default is
 	`custom-initialize-reset'.
 :set	VALUE should be a function to set the value of the symbol
-	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'.  If this keyword is
-	defined, modifying the value of SYMBOL via `setopt' will call the
+	when using the Customize user interface.  It takes two
+        mandatory arguments, the symbol to set and the value to give
+        it, and one optional argument, which, if its value is
+        `buffer-local', means the value should be set
+        buffer-locally, without affecting the global or default
+        value.  The function should not modify its value argument
+        destructively.  The default choice 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