From c3735f3b598ceb4144c1c0c5e804b1c368ea5d1e Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 7 Jul 2024 14:50:18 +0200 Subject: [PATCH] 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) --- lisp/progmodes/cperl-mode.el | 8 ++++---- lisp/progmodes/eglot.el | 10 +++++----- lisp/progmodes/etags.el | 4 ++-- lisp/progmodes/flymake.el | 2 +- lisp/progmodes/gdb-mi.el | 8 ++++---- lisp/progmodes/hideif.el | 2 +- lisp/progmodes/idlw-help.el | 4 ++-- lisp/progmodes/idlwave.el | 2 +- lisp/progmodes/java-ts-mode.el | 4 ++-- lisp/progmodes/js.el | 2 +- lisp/progmodes/pascal.el | 8 +++++--- lisp/progmodes/python.el | 4 ++-- lisp/progmodes/ruby-mode.el | 6 +++--- lisp/progmodes/rust-ts-mode.el | 2 +- lisp/progmodes/verilog-mode.el | 6 +++--- lisp/progmodes/xref.el | 2 +- 16 files changed, 38 insertions(+), 36 deletions(-) diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el index 68ad7eda9a7..217125e1599 100644 --- 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 9c51e9b578d..a893a8d749a 100644 --- 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 bcff0de7e16..575418703ce 100644 --- 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 6cc7d5c43aa..3321ae243a0 100644 --- 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 0ce5e1df794..2981965ee0c 100644 --- 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 a0d60b64788..2a5c0aeed1b 100644 --- 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 7bed69a738b..c311e1c5377 100644 --- 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 b9766bdbeb7..3628449d8e1 100644 --- 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 bb4a7df3340..4ceb211ade1 100644 --- 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 31e8f2924ac..f8140c14a49 100644 --- 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 bd39b64aefc..802c02dcfa4 100644 --- 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.\\ + "Major mode for editing Pascal code. +\\ 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.\\ + "Put the region into a Pascal comment. +\\ 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 73d6bdd2d2d..a00289d6de9 100644 --- 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 f6ef175e11e..3bcfa9ee7df 100644 --- 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 cdbf381d023..b7a52b06b24 100644 --- 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 192f4bd7e74..708aebf204d 100644 --- 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 abc7d7a3fc7..119daa71761 100644 --- 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) -- 2.39.2