From: Stefan Kangas <stefankangas@gmail.com>
Date: Tue, 11 Mar 2025 23:04:50 +0000 (+0100)
Subject: Automatically document when setopt is needed
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=99824b086c76e2d2eab1edb5ed06f553715c374d;p=emacs.git
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 5364c02c7a9..91a4bec619b 100644
--- 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 c74eec24f45..d700bbda856 100644
--- 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 5c953c252ec..65c7d414ff1 100644
--- 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 32985bac0e1..2a5ffb8c904 100644
--- 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 28b0e39af40..d4b82a01559 100644
--- 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 a53b33686c1..44184682901 100644
--- 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 2d019f54aec..cfacb144e40 100644
--- 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"