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.

(cherry picked from commit 77b7e2d37b2c68b73ad770ec680281c1f82d26f1)

diff --git a/lisp/follow.el b/lisp/follow.el
index 5364c02c7a97ed7c53dd4c7fe9234852b6103e09..91a4bec619b6fa927f8955cf92bd0b57852c32eb 100644 (file)
--- a/lisp/follow.el
+++ b/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)

diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index c74eec24f45b20a48cf57c002178878a48e34c61..d700bbda856e9a1664e8a2156c893394b2ae242e 100644 (file)
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -886,6 +886,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)))

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 5c953c252ec2864c63f5dd95ae9589342df90b34..65c7d414ff118c6a4445d9f049bd249a78908d1f 100644 (file)
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -6357,10 +6357,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)

diff --git a/lisp/savehist.el b/lisp/savehist.el
index 32985bac0e1a782f8cd6ea50d1a781aa719d4e68..2a5ffb8c904bc19afc733ef8b8be1e4d64f8d65e 100644 (file)
--- a/lisp/savehist.el
+++ b/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)

diff --git a/lisp/saveplace.el b/lisp/saveplace.el
index 28b0e39af40a9afc1284bfa989690a9d1db1ec4d..d4b82a01559c7954c1ecb8cdaa5cc1ca6e14dda6 100644 (file)
--- a/lisp/saveplace.el
+++ b/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"

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index a53b33686c10a56a8c428fbec0af0e4a069fbd2a..44184682901eb49df0d0fcbddef6d85f19be7b51 100644 (file)
--- a/lisp/tab-bar.el
+++ b/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)

diff --git a/lisp/textmodes/text-mode.el b/lisp/textmodes/text-mode.el
index 2d019f54aec730afa5db4de349e06be4f21ae19a..cfacb144e40379b315dc7e21d821288b40e94604 100644 (file)
--- a/lisp/textmodes/text-mode.el
+++ b/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"