emacs-30 186ea407326: Don't start docstrings with "This function" or similar

[Stefan Kangas]

branch: emacs-30
commit 186ea407326166ee4669ce6fe84871c1e16c657c
Author: Stefan Kangas <stefankangas@gmail.com>
Commit: Stefan Kangas <stefankangas@gmail.com>

    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".
---
 lisp/calculator.el        |  2 +-
 lisp/erc/erc-backend.el   |  2 +-
 lisp/erc/erc-log.el       |  4 ++--
 lisp/erc/erc-track.el     |  2 +-
 lisp/eshell/em-smart.el   |  2 +-
 lisp/eshell/esh-mode.el   |  2 +-
 lisp/gnus/gnus-art.el     |  2 +-
 lisp/mail/supercite.el    |  2 +-
 lisp/net/nsm.el           | 21 ++++++++++-----------
 lisp/org/org-element.el   |  2 +-
 lisp/progmodes/hideif.el  |  2 +-
 lisp/progmodes/modula2.el |  2 +-
 lisp/progmodes/xscheme.el |  8 ++++----
 lisp/tab-bar.el           |  2 +-
 lisp/which-key.el         |  2 +-
 15 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/lisp/calculator.el b/lisp/calculator.el
index ef1e6d8dbc3..5d1bb401f54 100644
--- a/lisp/calculator.el
+++ b/lisp/calculator.el
@@ -775,7 +775,7 @@ Defaults to 1."
   (or (nth 4 op) 1))
 
 (defun calculator-add-operators (more-ops)
-  "This function handles operator addition.
+  "Handle operator addition.
 Adds MORE-OPS to `calculator-operator', called initially to handle
 `calculator-initial-operators' and `calculator-user-operators'."
   (let ((added-ops nil))
diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el
index 9aedc110067..0720e46ef6b 100644
--- a/lisp/erc/erc-backend.el
+++ b/lisp/erc/erc-backend.el
@@ -570,7 +570,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 66420662c23..b37fa086a0e 100644
--- a/lisp/erc/erc-log.el
+++ b/lisp/erc/erc-log.el
@@ -352,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)
-  "This function computes a short log file name.
+  "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)
-  "This function computes 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
diff --git a/lisp/erc/erc-track.el b/lisp/erc/erc-track.el
index 39a4775ddca..6c91d88a168 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 34ce82cfbc4..30063fdacc9 100644
--- a/lisp/eshell/esh-mode.el
+++ b/lisp/eshell/esh-mode.el
@@ -534,7 +534,7 @@ Putting this function on `eshell-pre-command-hook' will 
mimic Plan 9's
     (eshell-interactive-filter nil string)))
 
 (defsubst eshell-begin-on-new-line ()
-  "This function outputs 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 5151ad1c1b8..c2264d1f5d0 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 add1582d72a..a620a14af1e 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 3d0eacf4eb2..4c87ed4a126 100644
--- a/lisp/net/nsm.el
+++ b/lisp/net/nsm.el
@@ -155,17 +155,16 @@ 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/hideif.el b/lisp/progmodes/hideif.el
index 9bcac0d8dc5..27a02e9805f 100644
--- a/lisp/progmodes/hideif.el
+++ b/lisp/progmodes/hideif.el
@@ -400,7 +400,7 @@ If there is a marked region from START to END it only shows 
the symbols within."
     (end-of-line 2)))
 
 (defun hif-merge-ifdef-region (start end)
-  "This function merges nearby ifdef regions to form a bigger overlay.
+  "Merge nearby ifdef regions to form a bigger overlay.
 The region is defined by START and END.  This will decrease the number of
 overlays created."
   ;; Generally there is no need to call itself recursively since there should
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.")
diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index e8c6b7f3bcc..2d530930649 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -298,7 +298,7 @@ For any other value of KEY, the value is t."
 (defvar tab-bar--dragging-in-progress)
 
 (defun tab-bar--event-to-item (posn)
-  "This function extracts extra info from the mouse event at position POSN.
+  "Extract extra info from the mouse event at position POSN.
 It returns a list of the form (KEY KEY-BINDING CLOSE-P), where:
  KEY is a symbol representing a tab, such as \\='tab-1 or \\='current-tab;
  KEY-BINDING is the binding of KEY;
diff --git a/lisp/which-key.el b/lisp/which-key.el
index 0118c0f74ef..f91ff78849b 100644
--- a/lisp/which-key.el
+++ b/lisp/which-key.el
@@ -1220,7 +1220,7 @@ total height."
 ;;; Show/hide which-key buffer
 
 (defun which-key--hide-popup ()
-  "This function is called to hide the which-key buffer."
+  "Hide the which-key buffer."
   (unless (or which-key-persistent-popup
               (member real-this-command which-key--paging-functions))
     (setq which-key--last-try-2-loc nil)