From 99824b086c76e2d2eab1edb5ed06f553715c374d Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Wed, 12 Mar 2025 00:04:50 +0100 Subject: [PATCH] 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) --- lisp/follow.el | 5 +---- lisp/help-fns.el | 13 +++++++++++++ lisp/minibuffer.el | 5 +---- lisp/savehist.el | 3 +-- lisp/saveplace.el | 3 +-- lisp/tab-bar.el | 4 +--- lisp/textmodes/text-mode.el | 5 +---- 7 files changed, 19 insertions(+), 19 deletions(-) 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" -- 2.39.5