Automatically document when setopt is needed

* lisp/help-fns.el (help--recommend-setopt): New function to
automatically document the need to use `setopt` to set the values of
any defcustoms with a `:set` property.
(help-fns-describe-variable-functions): Add above new function to
hook.

* lisp/follow.el (follow-mode-prefix-key):
* lisp/minibuffer.el (minibuffer-regexp-prompts):
* lisp/register.el (register-use-preview):
* lisp/savehist.el (savehist-autosave-interval):
* lisp/saveplace.el (save-place-autosave-interval):
* lisp/tab-bar.el (tab-bar-define-keys):
* lisp/textmodes/text-mode.el (text-mode-ispell-word-completion):
Delete now redundant text from docstrings.

etc/NEWS

@@ -386,13 +386,22 @@ Setting this variable to a non-nil value reduces performance and leads
 to wrong results in some cases.  We believe that it is no longer useful;
 please contact us if you still need it for some reason.
 
+---
 ** 'byte-compile-cond-use-jump-table' is now obsolete.
+
 ---
 ** Modified settings for an enabled theme now apply immediately.
 Evaluating a custom-theme-set-faces or custom-theme-set-variables
 call for an enabled theme causes the settings to apply immediately,
 without a need to re-load the theme.
 
+---
+** 'describe-variable' now automatically says if 'setopt' is needed.
+If a user option has a defcustom :set function, users will normally need
+to set it with 'setopt' for it to take an effect.  If the docstring
+doesn't already mention 'setopt', the 'describe-variable' command will
+now add a note about this automatically.
+
 
 * Editing Changes in Emacs 31.1
 

lisp/follow.el

@@ -230,10 +230,7 @@ After that, changing the prefix key requires manipulating keymaps."
 (make-obsolete-variable 'follow-mode-prefix 'follow-mode-prefix-key "31.1")
 
 (defcustom follow-mode-prefix-key (key-description follow-mode-prefix)
-  "Prefix key to use for follow commands in Follow mode.
-
-Setting this variable with `setq' has no effect; use either `setopt'
-or `customize-option' to change its value."
+  "Prefix key to use for follow commands in Follow mode."
   :type 'string
   :set (lambda (symbol value)
          (defvar follow-mode-map) (defvar follow-mode-submap)

lisp/help-fns.el

@@ -868,6 +868,19 @@ the C sources, too."
              (function-get function 'disabled))
     (insert "  This function is disabled.\n")))
 
+(add-hook 'help-fns-describe-variable-functions #'help--recommend-setopt)
+(defun help--recommend-setopt (symbol)
+  ;; TODO: This would be better if added to the docstring itself, but I
+  ;;       ran into `byte-compile-dynamic-docstring' and gave up.
+  (when (and (get symbol 'custom-set)
+             ;; Don't override manually written documentation.
+             (not (string-match (rx word-start "setopt" word-end)
+                                (get symbol 'variable-documentation))))
+    ;; FIXME: `princ` removes text properties added by s-c-k.
+    (princ (substitute-command-keys "\
+Setting this variable with `setq' has no effect; use either `setopt'
+or \\[customize-option] to change its value.\n\n"))))
+
 (defun help-fns--first-release-regexp (symbol)
   (let* ((name (symbol-name symbol))
          (quoted (regexp-quote name)))

lisp/minibuffer.el

@@ -5285,10 +5285,7 @@ and `blink-matching-paren' more user-friendly."
   "List of regular expressions that trigger `minibuffer-regexp-mode' features.
 The features of `minibuffer-regexp-mode' will be activated in a minibuffer
 interaction if and only if a prompt matching some regexp in this list
-appears at the beginning of the minibuffer.
-
-Setting this variable directly with `setq' has no effect; instead,
-either use \\[customize-option] interactively or use `setopt'."
+appears at the beginning of the minibuffer."
   :type '(repeat (string :tag "Prompt"))
   :set (lambda (sym val)
 	 (set-default sym val)

lisp/register.el

@@ -147,10 +147,7 @@ all; the preview buffer is still accessible with `help-char' (\\`C-h').
 
 When set to `traditional' (the default), provide a more basic preview
 according to `register-preview-delay'; this preserves the traditional
-behavior of Emacs 29 and before.
-
-Setting this variable with `setq' has no effect; use either `setopt'
-or `customize-option' to change its value."
+behavior of Emacs 29 and before."
   :type '(choice
           (const :tag "Use preview" t)
           (const :tag "Use preview and exit by pressing register name" insist)

lisp/savehist.el

@@ -121,8 +121,7 @@ executes in under 5 ms on my system."
 
 (defcustom savehist-autosave-interval (* 5 60)
   "The interval between autosaves of minibuffer history.
-If set to nil, disables timer-based autosaving.
-Use `setopt' or Customize commands to set this option."
+If set to nil, disables timer-based autosaving."
   :type '(choice (const :tag "Disabled" nil)
                  (integer :tag "Seconds"))
   :set (lambda (sym val)

lisp/saveplace.el

@@ -235,8 +235,7 @@ If `save-place-mode' is enabled, set the timer, otherwise cancel the timer."
 
 (defcustom save-place-autosave-interval nil
   "The interval between auto saves of buffer places.
-If set to nil, disables timer-based auto saving.
-Use `setopt' or Customize commands to set this option."
+If set to nil, disables timer-based auto saving."
   :type '(choice (const :tag "Disabled" nil)
                  (integer :tag "Seconds"))
   :version "31.1"

lisp/tab-bar.el

@@ -109,9 +109,7 @@ conjunction with `tab-bar-select-tab-modifiers', which see.
 
 If \\='tab, define only TAB and SHIFT-TAB tab-selection key mappings.
 
-If nil, do not define any key mappings.
-
-Customize this option, or use `setopt' to ensure it will take effect."
+If nil, do not define any key mappings."
   :type '(choice (const :tag "All keys" t)
                  (const :tag "Numeric tab selection keys" numeric)
                  (const :tag "TAB and SHIFT-TAB selection keys" tab)

lisp/textmodes/text-mode.el

@@ -83,10 +83,7 @@ means that Text mode adds an Ispell word completion function to
 `completion-at-point-functions'.  Any other non-nil value says to
 bind M-TAB directly to `ispell-complete-word' instead.  If this
 is nil, Text mode neither binds M-TAB to `ispell-complete-word'
-nor does it extend `completion-at-point-functions'.
-
-This user option only takes effect when you customize it in
-Custom or with `setopt', not with `setq'."
+nor does it extend `completion-at-point-functions'."
   :group 'text
   :type '(choice (const completion-at-point) boolean)
   :version "30.1"