Checkdoc fixes in progmodes

* lisp/progmodes/cperl-mode.el (cperl-file-style)
(cperl-continued-brace-offset, cperl-tips-faces):
* lisp/progmodes/eglot.el (eglot-confirm-server-edits, eglot)
(eglot-list-connections-mode, eglot--outstanding-inlay-hints-region)
(eglot--outstanding-inlay-regions-timer):
* lisp/progmodes/etags.el (etags-goto-tag-location)
(etags--xref-apropos-additional):
* lisp/progmodes/flymake.el (flymake-autoresize-margins):
* lisp/progmodes/gdb-mi.el (gdb-mouse-until, gdb-mouse-jump):
* lisp/progmodes/hideif.el (hif-parse-macro-arglist):
* lisp/progmodes/idlw-help.el (idlwave-html-help-location):
* lisp/progmodes/idlwave.el (idlwave-reserved-word-upcase):
* lisp/progmodes/java-ts-mode.el (java-ts-mode--string-highlight-helper):
* lisp/progmodes/js.el (js--chained-expression-p):
* lisp/progmodes/pascal.el (pascal-mode, pascal-comment-area):
* lisp/progmodes/python.el (python--treesit-fontify-union-types):
* lisp/progmodes/ruby-mode.el (ruby-align-chained-calls)
(ruby-block-indent, ruby-rubocop-use-bundler):
* lisp/progmodes/rust-ts-mode.el
(rust-ts-mode--prettify-symbols-compose-p):
* lisp/progmodes/verilog-mode.el (verilog-cache-has-lisp)
(verilog-auto-insert-lisp, verilog-highlight-region):
* lisp/progmodes/xref.el (xref--get-history): Various checkdoc fixes.

(cherry picked from commit 47c79b62dd04e9ec585354b35e0ef3b3e8c2878d)

diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el
index 68ad7eda9a73f1b39ad85f0391a1cbc182a3d057..217125e1599c96655006cef651b7b0fb8b2cb362 100644 (file)
--- a/lisp/progmodes/cperl-mode.el
+++ b/lisp/progmodes/cperl-mode.el
@@ -161,13 +161,13 @@ for constructs with multiline if/unless/while/until/for/foreach condition."
   :group 'cperl-autoinsert-details)
 
 (defcustom cperl-file-style nil
-  "Indentation style to use in cperl-mode.
+  "Indentation style to use in `cperl-mode'.
 Setting this option will override options as given in
 `cperl-style-alist' for the keyword provided here.  If nil, then
 the individual options as customized are used.
 \"PBP\" is the style recommended in the Book \"Perl Best
 Practices\" by Damian Conway.  \"CPerl\" is the traditional style
-of cperl-mode, and \"PerlStyle\" follows the Perl documentation
+of `cperl-mode', and \"PerlStyle\" follows the Perl documentation
 in perlstyle.  The other styles have been developed for other
 programming languages, mostly C."
   :type '(choice (const "PBP")
@@ -232,7 +232,7 @@ to the right of the start of its line."
   :group 'cperl-indentation-details)
 (defcustom cperl-continued-brace-offset 0
   "Extra indent for substatements that start with open-braces.
-This is in addition to cperl-continued-statement-offset."
+This is in addition to `cperl-continued-statement-offset'."
   :type 'integer
   :group 'cperl-indentation-details)
 (defcustom cperl-close-paren-offset -1
@@ -819,7 +819,7 @@ B) Speed of editing operations.
     of, say, long POD sections.")
 
 (defvar cperl-tips-faces 'please-ignore-this-line
-  "CPerl mode uses following faces for highlighting:
+  "CPerl mode uses the following faces for highlighting:
 
   `cperl-array-face'                   Array names
   `cperl-hash-face'                    Hash names

diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 9c51e9b578dd180649307dd708707cd7c353e19f..a893a8d749a01c0ac96a17c3f725187445fc5802 100644 (file)
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -494,7 +494,7 @@ If this variable's value can also be an alist ((COMMAND . ACTION)
 ...) where COMMAND is a symbol designating a command, such as
 `eglot-rename', `eglot-code-actions',
 `eglot-code-action-quickfix', etc.  ACTION is one of the symbols
-described above.  The value `t' for COMMAND is accepted and its
+described above.  The value t for COMMAND is accepted and its
 ACTION is the default value for commands not in the alist."
   :type (let ((basic-choices
                '((const :tag "Use diff" diff)
@@ -1415,7 +1415,7 @@ INTERACTIVE is ignored and provided for backward compatibility."
      (unless (or (null current-server)
                  (y-or-n-p "\
 [eglot] Shut down current connection before attempting new one?"))
-       (user-error "[eglot] Connection attempt aborted by user."))
+       (user-error "[eglot] Connection attempt aborted by user"))
      (prog1 (append (eglot--guess-contact t) '(t))
        (when current-server (ignore-errors (eglot-shutdown current-server))))))
   (eglot--connect (eglot--ensure-list managed-major-modes)
@@ -4019,7 +4019,7 @@ If NOERROR, return predicate, else erroring function."
 ;;; List connections mode
 
 (define-derived-mode eglot-list-connections-mode  tabulated-list-mode
-  "" "Eglot mode for listing server connections
+  "" "Eglot mode for listing server connections.
 \\{eglot-list-connections-mode-map}"
   :interactive nil
   (setq-local tabulated-list-format
@@ -4061,12 +4061,12 @@ If NOERROR, return predicate, else erroring function."
   "Face used for parameter inlay hint overlays.")
 
 (defvar-local eglot--outstanding-inlay-hints-region (cons nil nil)
-  "Jit-lock-calculated (FROM . TO) region with potentially outdated hints")
+  "Jit-lock-calculated (FROM . TO) region with potentially outdated hints.")
 
 (defvar-local eglot--outstanding-inlay-hints-last-region nil)
 
 (defvar-local eglot--outstanding-inlay-regions-timer nil
-  "Helper timer for `eglot--update-hints'")
+  "Helper timer for `eglot--update-hints'.")
 
 (defun eglot--update-hints (from to)
   "Jit-lock function for Eglot inlay hints."

diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index bcff0de7e16c4b43aa642f71f3f8236500213508..575418703ce1a7ab5d5aa65a3105acdd1163fbeb 100644 (file)
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -1359,7 +1359,7 @@ hits the start of file."
        (cond (line (progn (goto-char (point-min))
                           (forward-line (1- line))))
              (startpos (goto-char startpos))
-             (t (error "etags.el BUG: bogus direct file tag")))
+              (t (error "etags.el: BUG: bogus direct file tag")))
       ;; This constant is 1/2 the initial search window.
       ;; There is no sense in making it too small,
       ;; since just going around the loop once probably
@@ -2177,7 +2177,7 @@ file name, add `tag-partial-file-name-match-p' to the list value.")
        (when (symbolp symbs)
          (if (boundp symbs)
              (setq symbs (symbol-value symbs))
-           (warn "symbol `%s' has no value" symbs)
+           (warn "Symbol `%s' has no value" symbs)
            (setq symbs nil))
          (if (obarrayp symbs)
              (mapatoms add-xref symbs)

diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index 6cc7d5c43aab5109e2fee9893f39ce9d1631d2a4..3321ae243a0ec076c0419e83bf3bac3ce64f02a5 100644 (file)
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -218,7 +218,7 @@ this is used."
                        (face :tag "Face"))))
 
 (defcustom flymake-autoresize-margins t
-  "If non-nil, automatically resize margin-width calling flymake--resize-margins.
+  "If non-nil, automatically resize margin-width calling `flymake--resize-margins'.
 
 Only relevant if `flymake-indicator-type' is set to margins."
   :version "30.1"

diff --git a/lisp/progmodes/gdb-mi.el b/lisp/progmodes/gdb-mi.el
index 0ce5e1df794b87df346bbee53914a94d17b65700..2981965ee0cb774dd4baa822af81700687b28cb3 100644 (file)
--- a/lisp/progmodes/gdb-mi.el
+++ b/lisp/progmodes/gdb-mi.el
@@ -1285,8 +1285,8 @@ no input, and GDB is waiting for input."
 (defun gdb-mouse-until (event)
   "Continue running until a source line past the current line.
 The destination source line can be selected either by clicking
-with mouse-3 on the fringe/margin or dragging the arrow
-with mouse-1 (default bindings)."
+with \\`mouse-3' on the fringe/margin or dragging the arrow
+with \\`mouse-1' (default bindings)."
   (interactive "e")
   (let ((start (event-start event))
        (end (event-end event)))
@@ -1302,8 +1302,8 @@ with mouse-1 (default bindings)."
 
 (defun gdb-mouse-jump (event)
   "Set execution address/line.
-The destination source line can be selected either by clicking with C-mouse-3
-on the fringe/margin or dragging the arrow with C-mouse-1 (default bindings).
+The destination source line can be selected either by clicking with \\`C-mouse-3'
+on the fringe/margin or dragging the arrow with \\`C-mouse-1' (default bindings).
 Unlike `gdb-mouse-until' the destination address can be before the current
 line, and no execution takes place."
   (interactive "e")

diff --git a/lisp/progmodes/hideif.el b/lisp/progmodes/hideif.el
index a0d60b6478865976f857d75a5ba2c104a8673273..2a5c0aeed1b225537b8ef2789002f0aa6288d552 100644 (file)
--- a/lisp/progmodes/hideif.el
+++ b/lisp/progmodes/hideif.el
@@ -2400,7 +2400,7 @@ first arg will be `hif-etc'."
                       'c99 t)))
        ((eq token 'hif-comma)
         (if etc
-            (error "Syntax error: no comma allowed after `...'.")))
+            (error "Syntax error: no comma allowed after `...'")))
        (t
         (push token result))))
     (setq result (nreverse result))

diff --git a/lisp/progmodes/idlw-help.el b/lisp/progmodes/idlw-help.el
index 7bed69a738b8fae4085cbe600a1bf6b07f70f900..c311e1c537738c20754c6deb684e6b575d19b73a 100644 (file)
--- a/lisp/progmodes/idlw-help.el
+++ b/lisp/progmodes/idlw-help.el
@@ -62,8 +62,8 @@ is used in preference to the old `idlwave-html-help-location'."
    (if (memq system-type '(ms-dos windows-nt))
       nil
     "/usr/local/etc/")
-  "The directory where the idl_html_help/ dir lives.  Obsolete for IDL
-6.2 or later (see `idlwave-html-system-help-location')."
+  "The directory where the idl_html_help/ dir lives.
+Obsolete for IDL 6.2 or later (see `idlwave-html-system-help-location')."
   :type 'directory)
 
 (defcustom idlwave-help-use-assistant t

diff --git a/lisp/progmodes/idlwave.el b/lisp/progmodes/idlwave.el
index b9766bdbeb72bd578a1093726bbbc657ec47a295..3628449d8e1a32b3aec218bcdac8d235f5a5d776 100644 (file)
--- a/lisp/progmodes/idlwave.el
+++ b/lisp/progmodes/idlwave.el
@@ -798,7 +798,7 @@ upper case, regardless of this variable."
 (defcustom idlwave-reserved-word-upcase nil
   "Non-nil means, reserved words will be made upper case via abbrev expansion.
 If nil case of reserved words is controlled by `idlwave-abbrev-change-case'.
-Has effect only if in abbrev-mode."
+Has effect only if in `abbrev-mode'."
   :group 'idlwave-abbrev-and-indent-action
   :type 'boolean)
 

diff --git a/lisp/progmodes/java-ts-mode.el b/lisp/progmodes/java-ts-mode.el
index bb4a7df3340e53a6320bf877ef6bc23c3c1552a0..4ceb211ade11f1a24ff9920f28e37f412f71175f 100644 (file)
--- a/lisp/progmodes/java-ts-mode.el
+++ b/lisp/progmodes/java-ts-mode.el
@@ -155,8 +155,8 @@
   "Java operators for tree-sitter font-locking.")
 
 (defun java-ts-mode--string-highlight-helper ()
-"Returns, for strings, a query based on what is supported by
-the available version of Tree-sitter for java."
+  "Return, for strings, a query based on what is supported by
+the available version of Tree-sitter for Java."
   (condition-case nil
       (progn (treesit-query-capture 'java '((text_block) @font-lock-string-face))
             `((string_literal) @font-lock-string-face

diff --git a/lisp/progmodes/js.el b/lisp/progmodes/js.el
index 31e8f2924ac08193a8d7c3e201d1930605d7f111..f8140c14a498193ce36a4e4cf8568602a49b43da 100644 (file)
--- a/lisp/progmodes/js.el
+++ b/lisp/progmodes/js.el
@@ -2493,7 +2493,7 @@ Returns t if successful, nil if no term was found."
       t)))
 
 (defun js--chained-expression-p ()
-  "A helper for js--proper-indentation that handles chained expressions.
+  "Helper for `js--proper-indentation' that handles chained expressions.
 A chained expression is when the current line starts with '.' and the
 previous line also has a '.' expression.
 This function returns the indentation for the current line if it is

diff --git a/lisp/progmodes/pascal.el b/lisp/progmodes/pascal.el
index bd39b64aefcc65362d700a7861117016b15119f0..802c02dcfa478f84eb811e246a58f06350a2805e 100644 (file)
--- a/lisp/progmodes/pascal.el
+++ b/lisp/progmodes/pascal.el
@@ -297,7 +297,8 @@ are handled in another way, and should not be added to this list."
 
 ;;;###autoload
 (define-derived-mode pascal-mode prog-mode "Pascal"
-  "Major mode for editing Pascal code.\\<pascal-mode-map>
+  "Major mode for editing Pascal code.
+\\<pascal-mode-map>
 TAB indents for Pascal code.  Delete converts tabs to spaces as it moves back.
 
 \\[completion-at-point] completes the word around current point with respect \
@@ -333,7 +334,7 @@ Variables controlling indentation/edit style:
     regardless of where in the line point is when the TAB command is used.
  `pascal-auto-endcomments' (default t)
     Non-nil means a comment { ... } is set after the ends which ends cases and
-    functions. The name of the function or case will be set between the braces.
+    functions.  The name of the function or case will be set between the braces.
  `pascal-auto-lineup' (default t)
     List of contexts where auto lineup of :'s or ='s should be done.
 
@@ -496,7 +497,8 @@ This puts the mark at the end, and point at the beginning."
   (pascal-beg-of-defun))
 
 (defun pascal-comment-area (start end)
-  "Put the region into a Pascal comment.\\<pascal-mode-map>
+  "Put the region into a Pascal comment.
+\\<pascal-mode-map>
 The comments that are in this area are \"deformed\":
 `*)' becomes `!(*' and `}' becomes `!{'.
 These deformed comments are returned to normal if you use

diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index 73d6bdd2d2d25f88703c3b0661465309f0de5a34..a00289d6de9c42117ed2c303c7836c0a9fc7b091 100644 (file)
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -1140,8 +1140,8 @@ fontified."
 For example, Lvl1 | Lvl2[Lvl3[Lvl4[Lvl5 | None]], Lvl2].  This
 structure is represented via nesting binary_operator and
 subscript nodes.  This function iterates over all levels and
-highlight identifier nodes. If TYPE-REGEX is not nil fontify type
-identifier only if it matches against TYPE-REGEX. NODE is the
+highlight identifier nodes.  If TYPE-REGEX is not nil fontify type
+identifier only if it matches against TYPE-REGEX.  NODE is the
 binary_operator node.  OVERRIDE is the override flag described in
 `treesit-font-lock-rules'.  START and END mark the region to be
 fontified."

diff --git a/lisp/progmodes/ruby-mode.el b/lisp/progmodes/ruby-mode.el
index f6ef175e11e8fbcdb06b8d778aa8144c866daff3..3bcfa9ee7df2c07262af880522d203cba4c7864e 100644 (file)
--- a/lisp/progmodes/ruby-mode.el
+++ b/lisp/progmodes/ruby-mode.el
@@ -336,7 +336,7 @@ Only has effect when `ruby-use-smie' is t."
   "If non-nil, align chained method calls.
 
 Each method call on a separate line will be aligned to the column
-of its parent. Example:
+of its parent.  Example:
 
   my_array.select { |str| str.size > 5 }
           .map    { |str| str.downcase }
@@ -386,7 +386,7 @@ Only has effect when `ruby-use-smie' is t."
   "Non-nil to align the body of a block to the statement's start.
 
 The body and the closer will be aligned to the column where the
-statement containing the block starts. Example:
+statement containing the block starts.  Example:
 
   foo.bar
     .each do
@@ -2557,7 +2557,7 @@ If there is no Rubocop config file, Rubocop will be passed a flag
   "Non-nil with allow `ruby-flymake-rubocop' to use `bundle exec'.
 When the value is `check', it will first see whether Gemfile exists in
 the same directory as the configuration file, and whether it mentions
-the gem \"rubocop\".  When t, it's used unconditionally.  "
+the gem \"rubocop\".  When t, it is used unconditionally."
   :type '(choice (const :tag "Always" t)
                  (const :tag "No" nil)
                  (const :tag "If rubocop is in Gemfile" check))

diff --git a/lisp/progmodes/rust-ts-mode.el b/lisp/progmodes/rust-ts-mode.el
index cdbf381d023fe1fa8c2f77b711c3f7e9d858c981..b7a52b06b244bb5b376dc22f5b8f087bc19ddd88 100644 (file)
--- a/lisp/progmodes/rust-ts-mode.el
+++ b/lisp/progmodes/rust-ts-mode.el
@@ -431,7 +431,7 @@ delimiters < and >'s."
                             (?> '(5 . ?<))))))))
 
 (defun rust-ts-mode--prettify-symbols-compose-p (start end match)
-  "Return true iff the symbol MATCH should be composed.
+  "Return non-nil if the symbol MATCH should be composed.
 See `prettify-symbols-compose-predicate'."
   (and (fboundp 'prettify-symbols-default-compose-p)
        (prettify-symbols-default-compose-p start end match)

diff --git a/lisp/progmodes/verilog-mode.el b/lisp/progmodes/verilog-mode.el
index 192f4bd7e74c131e9ffe69557e9a6d45a56182e8..708aebf204d5959161f1f8a546d74435c5f0a5fb 100644 (file)
--- a/lisp/progmodes/verilog-mode.el
+++ b/lisp/progmodes/verilog-mode.el
@@ -9947,7 +9947,7 @@ For example if declare A A (.B(SIG)) then B will be included in the list."
           (setq sig-list (cons (list (match-string-no-properties 1) nil nil) sig-list))))
       sig-list)))
 
-(defvar verilog-cache-has-lisp nil "True if any AUTO_LISP in buffer.")
+(defvar verilog-cache-has-lisp nil "Non-nil if any AUTO_LISP in buffer.")
 (make-variable-buffer-local 'verilog-cache-has-lisp)
 
 (defun verilog-read-auto-lisp-present ()
@@ -14040,7 +14040,7 @@ Typing \\[verilog-auto] will call my-verilog-insert-hello and
 expand the above into:
 
            /*AUTOINSERTLISP(my-verilog-insert-hello \"world\")*/
-           // Beginning of automatic insert lisp
+           // Beginning of automatic insert Lisp
            initial $write(\"hello world\");
            // End of automatics
 
@@ -15397,7 +15397,7 @@ and the case items."
 
 (defun verilog-highlight-region (beg end _old-len)
   "Colorize included files and modules in the (changed?) region.
-Clicking on the middle-mouse button loads them in a buffer (as in dired)."
+Clicking on the middle-mouse button loads them in a buffer (as in Dired)."
   (when (or verilog-highlight-includes
            verilog-highlight-modules)
     (save-excursion

diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index abc7d7a3fc7a21770a434ed52350ad2fa8add47f..119daa717616827485a48faea2fd494ff0134fbe 100644 (file)
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -502,7 +502,7 @@ Override existing value with NEW-VALUE if NEW-VALUE is set."
           (set-window-parameter w 'xref--history (xref--make-xref-history))))))
 
 (defun xref--get-history ()
-  "Return xref history using xref-history-storage."
+  "Return xref history using `xref-history-storage'."
   (funcall xref-history-storage))
 
 (defun xref--push-backward (m)