From: Stefan Kangas Date: Thu, 26 Dec 2024 20:02:45 +0000 (+0100) Subject: Don't start docstrings with "This function" or similar X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=85e5a63364211dc504de1fe7d008679df541bb54;p=emacs.git Don't start docstrings with "This function" or similar * lisp/calculator.el (calculator-add-operators): * lisp/erc/erc-backend.el (erc-server-ping-handler): * lisp/erc/erc-log.el (erc-generate-log-file-name-with-date): (erc-generate-log-file-name-short): * lisp/erc/erc-track.el (erc-track-shorten-function): * lisp/eshell/em-smart.el (eshell-where-to-jump): * lisp/eshell/esh-mode.el (eshell-begin-on-new-line): * lisp/gnus/gnus-art.el (gnus-prompt-before-saving): * lisp/mail/supercite.el (sc-cite-region-limit): * lisp/net/nsm.el (network-security-protocol-checks): * lisp/org/org-element.el (org-element--cache-avoid-synchronous-headline-re-parsing): * lisp/progmodes/hideif.el (hif-merge-ifdef-region): * lisp/progmodes/modula2.el (m2-indent): * lisp/progmodes/xscheme.el (xscheme-running-p): (xscheme-control-g-disabled-p): * lisp/tab-bar.el (tab-bar--event-to-item): * lisp/which-key.el (which-key--hide-popup): Don't start docstrings with "This function" or "This variable". (cherry picked from commit 186ea407326166ee4669ce6fe84871c1e16c657c) --- diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el index 5c55132a5e5..a5153df6fc3 100644 --- a/lisp/erc/erc-backend.el +++ b/lisp/erc/erc-backend.el @@ -571,7 +571,7 @@ If this is set to nil, never try to reconnect." (integer :tag "Seconds"))) (defvar-local erc-server-ping-handler nil - "This variable holds the periodic ping timer.") + "The periodic server ping timer.") ;;;; Helper functions diff --git a/lisp/erc/erc-log.el b/lisp/erc/erc-log.el index a1102ebdcdf..b37fa086a0e 100644 --- a/lisp/erc/erc-log.el +++ b/lisp/erc/erc-log.el @@ -231,7 +231,7 @@ also be a predicate function. To only log when you are not set away, use: (add-hook 'erc-part-hook #'erc-conditional-save-buffer) ;; append, so that 'erc-initialize-log-marker runs first (add-hook 'erc-connect-pre-hook #'erc-log-setup-logging 'append) - ;; FIXME use proper local "setup" function and major-mode hook. + (add-hook 'erc--pre-clear-functions #'erc-save-buffer-in-logs 50) (dolist (buffer (erc-buffer-list)) (erc-log-setup-logging buffer)) (erc--modify-local-map t "C-c C-l" #'erc-save-buffer-in-logs)) @@ -244,6 +244,7 @@ also be a predicate function. To only log when you are not set away, use: (remove-hook 'erc-quit-hook #'erc-conditional-save-queries) (remove-hook 'erc-part-hook #'erc-conditional-save-buffer) (remove-hook 'erc-connect-pre-hook #'erc-log-setup-logging) + (remove-hook 'erc--pre-clear-functions #'erc-save-buffer-in-logs) (dolist (buffer (erc-buffer-list)) (erc-log-disable-logging buffer)) (erc--modify-local-map nil "C-c C-l" #'erc-save-buffer-in-logs))) @@ -258,8 +259,6 @@ The current buffer is given by BUFFER." (auto-save-mode -1) (setq buffer-file-name nil) (add-hook 'write-file-functions #'erc-save-buffer-in-logs nil t) - (add-function :before (local 'erc--clear-function) - #'erc-log--save-on-clear '((depth . 50))) (when erc-log-insert-log-on-open (ignore-errors (save-excursion @@ -272,7 +271,6 @@ The current buffer is given by BUFFER." "Disable logging in BUFFER." (when (erc-logging-enabled buffer) (with-current-buffer buffer - (remove-function (local 'erc--clear-function) #'erc-log--save-on-clear) (setq buffer-offer-save nil erc-enable-logging nil)))) @@ -307,10 +305,6 @@ Return nil if BUFFER is a server buffer." (erc-save-buffer-in-logs buffer))) (defvar erc-log--save-in-progress-p nil) -;; The function `erc-directory-writable-p' may signal when HOME is not -;; writable, such as when running the test suite (/nonexistent). This -;; flag tells `erc-logging-enabled' to use `file-writable-p' instead. -(defvar erc-log--check-writable-nocreate-p nil) ;;;###autoload (defun erc-logging-enabled (&optional buffer) @@ -323,9 +317,7 @@ is writable (it will be created as necessary) and (and erc-log-channels-directory (not erc-log--save-in-progress-p) (or (functionp erc-log-channels-directory) - (if erc-log--check-writable-nocreate-p - (file-writable-p erc-log-channels-directory) - (erc-directory-writable-p erc-log-channels-directory))) + (erc-directory-writable-p erc-log-channels-directory)) (if (functionp erc-enable-logging) (funcall erc-enable-logging buffer) (buffer-local-value 'erc-enable-logging buffer)))) @@ -360,13 +352,13 @@ The result is converted to lowercase, as IRC is case-insensitive." erc-log-channels-directory))))) (defun erc-generate-log-file-name-with-date (buffer &rest _ignore) - "Compute a short log file name with the current date. + "Return a short log file name with the current date. The name of the log file is composed of BUFFER and the current date. This function is a possible value for `erc-generate-log-file-name-function'." (concat (buffer-name buffer) "-" (format-time-string "%Y-%m-%d") ".txt")) (defun erc-generate-log-file-name-short (buffer &rest _ignore) - "Compute a short log file name. + "Return a short log file name. In fact, it only uses the buffer name of the BUFFER argument, so you can affect that using `rename-buffer' and the-like. This function is a possible value for @@ -423,7 +415,6 @@ You can save every individual message by putting this function on (widen) ;; early on in the initialization, don't try and write the log out (when (and (markerp erc-last-saved-position) - (null erc--insert-marker) ; suppress when splicing (> erc-insert-marker (1+ erc-last-saved-position))) (let ((start (1+ (marker-position erc-last-saved-position))) (end (marker-position erc-insert-marker))) @@ -455,17 +446,14 @@ You can save every individual message by putting this function on (set-buffer-modified-p nil)))))) t) -(defun erc-log--save-on-clear (_ end) - (erc-save-buffer-in-logs end)) - -;; This exists to avoid littering erc-truncate.el with forward -;; declarations needed only for a compatibility check. -(defun erc-log--check-legacy-implicit-enabling-by-truncate () - "Return non-nil when conditions for legacy \"implicit\" activation are met. -This only concerns the \\+`truncate' module." - (and (not (or erc-log-mode (memq 'log erc-modules))) - (let ((erc-log--check-writable-nocreate-p t)) - (erc-logging-enabled)))) +;; This is a kludge to avoid littering erc-truncate.el with forward +;; declarations needed only for a corner-case compatibility check. +(defun erc-log--call-when-logging-enabled-sans-module (fn) + (when (and (erc-logging-enabled) + (not (or erc-log-mode (memq 'log erc-modules)))) + (let ((dirfile (and (stringp erc-log-channels-directory) + erc-log-channels-directory))) + (funcall fn dirfile)))) (provide 'erc-log) diff --git a/lisp/erc/erc-track.el b/lisp/erc/erc-track.el index 82e5f402910..d1c487de6f6 100644 --- a/lisp/erc/erc-track.el +++ b/lisp/erc/erc-track.el @@ -140,7 +140,7 @@ This setting is used by `erc-track-shorten-names'." (const :tag "Max" max))) (defcustom erc-track-shorten-function 'erc-track-shorten-names - "This function will be used to reduce the channel names before display. + "Function used to reduce the channel names before display. It takes one argument, CHANNEL-NAMES which is a list of strings. It should return a list of strings of the same number of elements. If nil instead of a function, shortening is disabled." diff --git a/lisp/eshell/em-smart.el b/lisp/eshell/em-smart.el index 670b956476d..c49b6a9caa3 100644 --- a/lisp/eshell/em-smart.el +++ b/lisp/eshell/em-smart.el @@ -150,7 +150,7 @@ buffer using \\[end-of-buffer]." :group 'eshell-smart) (defcustom eshell-where-to-jump 'begin - "This variable indicates where point should jump to after a command. + "The location where point should jump to after a command. The options are `begin', `after' or `end'." :type '(radio (const :tag "Beginning of command" begin) (const :tag "After command word" after) diff --git a/lisp/eshell/esh-mode.el b/lisp/eshell/esh-mode.el index 4f94934fccd..f4a405bfbfc 100644 --- a/lisp/eshell/esh-mode.el +++ b/lisp/eshell/esh-mode.el @@ -537,7 +537,7 @@ Putting this function on `eshell-pre-command-hook' will mimic Plan 9's (eshell-interactive-output-filter nil string))) (defsubst eshell-begin-on-new-line () - "Print a newline if not at beginning of line." + "Output a newline if not at beginning of line." (save-excursion (goto-char eshell-last-output-end) (or (bolp) diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el index b1d686e7da1..3052f1c0097 100644 --- a/lisp/gnus/gnus-art.el +++ b/lisp/gnus/gnus-art.el @@ -512,7 +512,7 @@ might have." :type 'boolean) (defcustom gnus-prompt-before-saving 'always - "This variable says how much prompting is to be done when saving articles. + "How much prompting to do when saving articles. If it is nil, no prompting will be done, and the articles will be saved to the default files. If this variable is `always', each and every article that is saved will be preceded by a prompt, even when diff --git a/lisp/mail/supercite.el b/lisp/mail/supercite.el index 1bc4111e79e..d979f97a17a 100644 --- a/lisp/mail/supercite.el +++ b/lisp/mail/supercite.el @@ -236,7 +236,7 @@ See the variable `sc-cite-frame-alist' for details." :group 'supercite-frames) (defcustom sc-cite-region-limit t - "This variable controls automatic citation of yanked text. + "Size limit for automatic citation of yanked text. Valid values are: non-nil -- cite the entire region, regardless of its size diff --git a/lisp/net/nsm.el b/lisp/net/nsm.el index 16aa5d689e1..e9e37a7eac1 100644 --- a/lisp/net/nsm.el +++ b/lisp/net/nsm.el @@ -154,17 +154,16 @@ If WARN-UNENCRYPTED, query the user if the connection is unencrypted." (dhe-kx high) (rsa-kx high) (cbc-cipher high)) - "This variable specifies what TLS connection checks to perform. -It's an alist where the key is the name of the check, and the -value is the minimum security level the check should begin. - -Each check function is called with the parameters HOST PORT -STATUS SETTINGS. HOST is the host domain, PORT is a TCP port -number, STATUS is the peer status returned by -`gnutls-peer-status', and SETTINGS is the persistent and session -settings for the host HOST. Please refer to the contents of -`nsm-settings-file' for details. If a problem is found, the check -function is required to return an error message, and nil + "Alist of TLS connection checks to perform. +The key is the name of the check, and the value is the minimum security +level the check should begin. + +Each check function is called with the parameters HOST PORT STATUS +SETTINGS. HOST is the host domain, PORT is a TCP port number, STATUS is +the peer status returned by `gnutls-peer-status', and SETTINGS is the +persistent and session settings for the host HOST. Please refer to the +contents of `nsm-settings-file' for details. If a problem is found, the +check function is required to return an error message, and nil otherwise. See also: `nsm-check-tls-connection', `nsm-save-host-names', diff --git a/lisp/org/org-element.el b/lisp/org/org-element.el index a3fe427403a..64a28510d51 100644 --- a/lisp/org/org-element.el +++ b/lisp/org/org-element.el @@ -7259,7 +7259,7 @@ that range. See `after-change-functions' for more information." #'org-element--cache-after-change -1 t))) (defvar org-element--cache-avoid-synchronous-headline-re-parsing nil - "This variable controls how buffer changes are handled by the cache. + "How buffer changes are handled by the cache. By default (when this variable is nil), cache re-parses modified headlines immediately after modification preserving all the unaffected diff --git a/lisp/progmodes/modula2.el b/lisp/progmodes/modula2.el index 2bb31988290..3950443c01e 100644 --- a/lisp/progmodes/modula2.el +++ b/lisp/progmodes/modula2.el @@ -97,7 +97,7 @@ "C-c C-c" #'m2-compile) (defcustom m2-indent 5 - "This variable gives the indentation in Modula-2 mode." + "Indentation in Modula-2 mode." :type 'integer :safe (lambda (v) (or (null v) (integerp v)))) diff --git a/lisp/progmodes/xscheme.el b/lisp/progmodes/xscheme.el index 598328dddea..b9c2ea95169 100644 --- a/lisp/progmodes/xscheme.el +++ b/lisp/progmodes/xscheme.el @@ -55,8 +55,8 @@ "The tail of the Scheme expressions ring whose car is the last thing yanked.") (defvar-local xscheme-running-p nil - "This variable, if nil, indicates that the scheme process is -waiting for input. Otherwise, it is busy evaluating something.") + "If nil, the scheme process is waiting for input. +Otherwise, it is busy evaluating something.") (defconst xscheme-control-g-synchronization-p t "If non-nil, insert markers in the scheme input stream to indicate when @@ -64,8 +64,8 @@ control-g interrupts were signaled. Do not allow more control-g's to be signaled until the scheme process acknowledges receipt.") (defvar-local xscheme-control-g-disabled-p nil - "This variable, if non-nil, indicates that a control-g is being processed -by the scheme process, so additional control-g's are to be ignored.") + "If non-nil, a control-g is being processed by the scheme process, so +additional control-g's are to be ignored.") (defvar xscheme-string-receiver nil "Procedure to send the string argument from the scheme process.")