Miscellaneous checkdoc fixes

skangas · skangas · commit e4760109ac8e · 2024-07-20T02:42:08.000+02:00
* lisp/ansi-color.el (ansi-color--ensure-context):
* lisp/doc-view.el (doc-view-svg-face):
* lisp/external-completion.el (external-completion-table):
* lisp/ffap.el (ffap-ro-mode-hook, ffap-gnus-hook):
* lisp/find-file.el:
* lisp/flow-ctrl.el (flow-control-c-s-replacement)
(flow-control-c-q-replacement):
* lisp/forms.el (forms-multi-line):
* lisp/help.el (search-forward-help-for-help):
* lisp/hi-lock.el (hi-lock-use-overlays):
* lisp/image.el (find-image):
* lisp/isearch.el (isearch-forward, isearch-forward-regexp)
(isearch-lazy-count-format):
* lisp/jsonrpc.el (jsonrpc--continue, initialize-instance):
* lisp/mouse-copy.el (mouse-kill-preserving-secondary):
* lisp/pixel-scroll.el (pixel-bob-at-top-p)
(pixel-scroll-down-and-set-window-vscroll):
* lisp/printing.el (pr-gv-command, pr-gs-command)
(pr-gs-switches):
* lisp/register.el (register-use-preview):
* lisp/repeat.el (repeat-check-key):
* lisp/saveplace.el (save-place-abbreviate-file-names):
* lisp/select.el (gui--clipboard-selection-unchanged-p):
* lisp/ses.el (ses-header-row):
* lisp/simple.el (transpose-sexps-default-function)
(normal-erase-is-backspace, normal-erase-is-backspace-mode):
* lisp/sqlite-mode.el (sqlite-mode):
* lisp/tempo.el (tempo-insert-region):
* lisp/term.el (term-mode-map, term-mode, term-char-mode):
Checkdoc fixes.
diff --git a/lisp/ansi-color.el b/lisp/ansi-color.el
@@ -565,12 +565,11 @@ This function can be added to `comint-preoutput-filter-functions'."
 
 (defun ansi-color--ensure-context (context-sym position)
   "Return CONTEXT-SYM's value as a valid context.
-If it is nil, set CONTEXT-SYM's value to a new context and return
-it. Context is a list of the form as described in
-`ansi-color-context' if POSITION is nil, or
-`ansi-color-context-region' if POSITION is non-nil.
+If it is nil, set CONTEXT-SYM's value to a new context and return it.
+Context is a list of the form as described in `ansi-color-context' if
+POSITION is nil, or `ansi-color-context-region' if POSITION is non-nil.
 
-If CONTEXT-SYM's value is already non-nil, return it. If its
+If CONTEXT-SYM's value is already non-nil, return it.  If its
 marker doesn't point anywhere yet, position it before character
 number POSITION, if non-nil."
   (let ((context (symbol-value context-sym)))
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
@@ -51,7 +51,7 @@
 ;; subdirectory of `doc-view-cache-directory' and reused when you want to view
 ;; that file again.  To reconvert a document hit `g' (`doc-view-reconvert-doc')
 ;; when displaying the document.  To delete all cached files use
-;; `doc-view-clear-cache'.  To open the cache with dired, so that you can tidy
+;; `doc-view-clear-cache'.  To open the cache with Dired, so that you can tidy
 ;; it out use `doc-view-dired-cache'.
 ;;
 ;; When conversion is underway the first page will be displayed as soon as it
@@ -239,8 +239,8 @@ showing only titles and no page number."
   :version "29.1")
 
 (defface doc-view-svg-face '((t :inherit default))
-  "Face used for SVG images.  Only background and foreground colors
-are used.
+  "Face used for SVG images.
+Only background and foreground colors are used.
 See `doc-view-mupdf-use-svg'."
   :version "30.1")
 
diff --git a/lisp/external-completion.el b/lisp/external-completion.el
@@ -75,7 +75,7 @@ function links CATEGORY to the style `external', by modifying
 set in `completion-styles'.
 
 LOOKUP is a function taking a string PATTERN and a number
-POINT. The function should contact the tool and return a list of
+POINT.  The function should contact the tool and return a list of
 strings representing the completions for PATTERN given that POINT
 is the location of point within it.  LOOKUP decides if PATTERN is
 interpreted as a substring, a regular expression, or any other
diff --git a/lisp/ffap.el b/lisp/ffap.el
@@ -1953,12 +1953,12 @@ Only intended for interactive use."
 ;; bindings you would prefer.
 
 (defun ffap-ro-mode-hook ()
-  "Bind `ffap-next' and `ffap-menu' to M-l and M-m, resp."
+  "Bind `ffap-next' and `ffap-menu' to \\`M-l' and \\`M-m', resp."
   (local-set-key "\M-l" 'ffap-next)
   (local-set-key "\M-m" 'ffap-menu))
 
 (defun ffap-gnus-hook ()
-  "Bind `ffap-gnus-next' and `ffap-gnus-menu' to M-l and M-m, resp."
+  "Bind `ffap-gnus-next' and `ffap-gnus-menu' to \\`M-l' and \\`M-m', resp."
   ;; message-id's
   (setq-local thing-at-point-default-mail-uri-scheme "news")
   ;; Note "l", "L", "m", "M" are taken:
diff --git a/lisp/find-file.el b/lisp/find-file.el
@@ -93,7 +93,7 @@
 ;;
 ;; GIVEN AN ARGUMENT (with the ^U prefix), ff-find-other-file will get the
 ;; other file in another (the other?) window (see find-file-other-window and
-;; switch-to-buffer-other-window). This can be set on a more permanent basis
+;; switch-to-buffer-other-window).  This can be set on a more permanent basis
 ;; by setting ff-always-in-other-window to t in which case the ^U prefix will
 ;; do the opposite of what was described above.
 ;;
diff --git a/lisp/flow-ctrl.el b/lisp/flow-ctrl.el
@@ -44,9 +44,9 @@
 ;;; Code:
 
 (defvar flow-control-c-s-replacement ?\034
-  "Character that replaces C-s, when flow control handling is enabled.")
+  "Character that replaces \\`C-s', when flow control handling is enabled.")
 (defvar flow-control-c-q-replacement ?\036
-  "Character that replaces C-q, when flow control handling is enabled.")
+  "Character that replaces \\`C-q', when flow control handling is enabled.")
 
 (put 'keyboard-translate-table 'char-table-extra-slots 0)
 
diff --git a/lisp/forms.el b/lisp/forms.el
@@ -323,8 +323,8 @@
   "Non-nil means: visit the file in view (read-only) mode.
 This is set automatically if the file permissions don't let you write it.")
 
-(defvar forms-multi-line "\C-k" "\
-If not nil: use this character to separate multi-line fields (default C-k).")
+(defvar forms-multi-line "\C-k"
+  "If non-nil, use this character to separate multi-line fields (default \\`C-k').")
 
 (defcustom forms-forms-scroll nil
   "Non-nil means replace scroll-up/down commands in Forms mode.
diff --git a/lisp/help.el b/lisp/help.el
@@ -1205,7 +1205,7 @@ current buffer."
 	    (describe-function-1 defn)))))))
 
 (defun search-forward-help-for-help ()
-  "Search forward in the help-for-help window.
+  "Search forward in the `help-for-help' window.
 This command is meant to be used after issuing the \\[help-for-help] command."
   (interactive)
   (unless (get-buffer help-for-help-buffer-name)
diff --git a/lisp/hi-lock.el b/lisp/hi-lock.el
@@ -751,7 +751,7 @@ with completion and history."
 
 (defvar hi-lock-use-overlays nil
   "Whether to always use overlays instead of font-lock rules.
-When font-lock-mode is enabled and the buffer specifies font-lock rules,
+When `font-lock-mode' is enabled and the buffer specifies font-lock rules,
 highlighting is performed by adding new font-lock rules to the existing ones,
 so when new matching strings are added, they are highlighted by font-lock.
 Otherwise, overlays are used, but new highlighting overlays are not added
diff --git a/lisp/image.el b/lisp/image.el
@@ -815,7 +815,7 @@ string containing the actual image data.  If the property `:type TYPE'
 is omitted or nil, try to determine the image type from its first few
 bytes of image data.  If that doesn't work, and the property `:file
 FILE' provide a file name, use its file extension as indication of the
-image type. If `:type TYPE' is provided, it must match the actual type
+image type.  If `:type TYPE' is provided, it must match the actual type
 determined for FILE or DATA by `create-image'.
 
 The function returns the image specification for the first specification
diff --git a/lisp/isearch.el b/lisp/isearch.el
@@ -1003,16 +1003,15 @@ Each element is an `isearch--state' struct where the slots are
 ;; Entry points to isearch-mode.
 
 (defun isearch-forward (&optional regexp-p no-recursive-edit)
-  "\
-Do incremental search forward.
+  "Do incremental search forward.
 With a prefix argument, do an incremental regular expression search instead.
 \\<isearch-mode-map>
 As you type characters, they add to the search string and are found.
 The following non-printing keys are bound in `isearch-mode-map'.
 
 Type \\[isearch-delete-char] to cancel last input item from end of search string.
 Type \\[isearch-exit] to exit, leaving point at location found.
-Type LFD (C-j) to match end of line.
+Type LFD (\\`C-j') to match end of line.
 Type \\[isearch-repeat-forward] to search again forward,\
  \\[isearch-repeat-backward] to search again backward.
 Type \\[isearch-beginning-of-buffer] to go to the first match,\
@@ -1110,7 +1109,7 @@ as a regexp.  See the command `isearch-forward' for more information.
 
 In incremental searches, a space or spaces normally matches any
 whitespace defined by the variable `search-whitespace-regexp'.
-To search for a literal space and nothing else, enter C-q SPC.
+To search for a literal space and nothing else, enter \\`C-q SPC'.
 To toggle whitespace matching, use `isearch-toggle-lax-whitespace',
 usually bound to \\`M-s SPC' during isearch.
 This command does not support character folding."
@@ -3557,7 +3556,8 @@ the word mode."
 (defun isearch-lazy-count-format (&optional suffix-p)
   "Format the current match number and the total number of matches.
 When SUFFIX-P is non-nil, the returned string is intended for
-isearch-message-suffix prompt.  Otherwise, for isearch-message-prefix."
+`isearch-message-suffix' prompt.  Otherwise, for
+`isearch-message-prefix'."
   (let ((format-string (if suffix-p
                            lazy-count-suffix-format
                          lazy-count-prefix-format)))
diff --git a/lisp/jsonrpc.el b/lisp/jsonrpc.el
@@ -125,7 +125,7 @@ size of the log buffer (0 disables, nil means infinite).  The
                            t))
   (when e-b-s-s-supplied-p
     (warn
-     "`:events-buffer-scrollback-size' deprecated. Use `events-buffer-config'.")
+     "`:events-buffer-scrollback-size' deprecated.  Use `events-buffer-config'.")
     (with-slots ((plist -events-buffer-config)) c
       (setf plist (copy-sequence plist)
             plist (plist-put plist :size events-buffer-scrollback-size)))))
@@ -825,7 +825,7 @@ Return the full continuation (ID SUCCESS-FN ERROR-FN TIMER)"
     (cond
      (anxious
       (when (not (= (car head) id)) ; sanity check
-        (error "internal error: please report this bug"))
+        (error "Internal error: please report this bug"))
       ;; If there are "anxious" `jsonrpc-request' continuations
       ;; that should already have been run, they should run now.
       ;; The main continuation -- if it exists -- should run
diff --git a/lisp/mouse-copy.el b/lisp/mouse-copy.el
@@ -184,10 +184,9 @@ put the point at one place, then click and drag over some other region."
 
 This command is like \\[mouse-kill-secondary] (that is, the secondary
 selection is deleted and placed in the kill ring), except that it also
-leaves the secondary buffer active on exit.
-
-This command was derived from mouse-kill-secondary in emacs-19.28
-by johnh@ficus.cs.ucla.edu."
+leaves the secondary buffer active on exit."
+  ;; This command was derived from mouse-kill-secondary in emacs-19.28
+  ;; by johnh@ficus.cs.ucla.edu.
   (interactive)
   (let* ((keys (this-command-keys))
 	 (click (elt keys (1- (length keys)))))
@@ -202,7 +201,7 @@ by johnh@ficus.cs.ucla.edu."
   ;; (delete-overlay mouse-secondary-overlay)
   ;; (gui-set-selection 'SECONDARY nil)
   ;; (setq mouse-secondary-overlay nil)
-)
+  )
 
 (defun mouse-drag-secondary-moving (start-event)
   "Sweep out a secondary selection, then move it to the current point."
diff --git a/lisp/pixel-scroll.el b/lisp/pixel-scroll.el
@@ -289,7 +289,7 @@ This is and alternative of `scroll-down'.  Scope moves upward."
 (put 'pixel-scroll-down 'scroll-command t)
 
 (defun pixel-bob-at-top-p (amt)
-  "Return non-nil if window-start is at beginning of the current buffer.
+  "Return non-nil if `window-start' is at beginning of the current buffer.
 Window must be vertically scrolled by not more than AMT pixels."
   (and (equal (window-start) (point-min))
        (< (window-vscroll nil t) amt)))
@@ -492,8 +492,8 @@ unseen line just above the scope of current window."
 
 (defun pixel-scroll-down-and-set-window-vscroll (vscroll)
   "Scroll down a line and set VSCROLL in pixels.
-It is important to call `set-window-start' to force the display
-engine use that particular position as the window-start point.
+It is important to call `set-window-start' to force the display engine
+to use that particular position as the `window-start' point.
 Otherwise, redisplay will reset the window's vscroll."
   (set-window-start nil (pixel-point-at-unseen-line) t)
   (set-window-vscroll nil vscroll t))
diff --git a/lisp/printing.el b/lisp/printing.el
@@ -1858,8 +1858,7 @@ Useful links:
   `http://pages.cs.wisc.edu/~ghost/gv/gv_doc/gv.html'
 
 * MacGSView (Mac OS)
-  `http://pages.cs.wisc.edu/~ghost/macos/index.htm'
-"
+  `http://pages.cs.wisc.edu/~ghost/macos/index.htm'"
   :type '(string :tag "Ghostview Utility"))
 
 
@@ -1883,8 +1882,7 @@ Useful links:
   `https://www.cs.wisc.edu/~ghost/doc/cvs/Use.htm'
 
 * Printer compatibility
-  `https://www.cs.wisc.edu/~ghost/doc/printer.htm'
-"
+  `https://www.cs.wisc.edu/~ghost/doc/printer.htm'"
   :type '(string :tag "Ghostscript Utility"))
 
 
@@ -1924,8 +1922,7 @@ Useful links:
   `https://www.cs.wisc.edu/~ghost/doc/cvs/Use.htm'
 
 * Printer compatibility
-  `https://www.cs.wisc.edu/~ghost/doc/printer.htm'
-"
+  `https://www.cs.wisc.edu/~ghost/doc/printer.htm'"
   :type '(repeat (string :tag "Ghostscript Switch")))
 
 
diff --git a/lisp/register.el b/lisp/register.el
@@ -131,16 +131,16 @@ to the value of `register--read-with-preview-function'.")
 (defcustom register-use-preview 'traditional
   "Whether to show register preview when modifying registers.
 
-When set to `t', show a preview buffer with navigation and
+When set to t, show a preview buffer with navigation and
 highlighting.
-When set to \\='insist, behave as with `t', but allow exiting the
+When set to \\='insist, behave as with t, but allow exiting the
 minibuffer by pressing the register name a second time.  E.g.,
 press \"a\" to select register \"a\", then press \"a\" again to
 exit the minibuffer.
 When nil, show a preview buffer without navigation and highlighting, and
 exit the minibuffer immediately after inserting response in minibuffer.
 When set to \\='never, behave as with nil, but with no preview buffer at
-all; the preview buffer is still accessible with `help-char' (C-h).
+all; the preview buffer is still accessible with `help-char' (\\`C-h').
 When set to \\='traditional (the default), provide a more basic preview
 according to `register-preview-delay'; this preserves the traditional
 behavior of Emacs 29 and before."
diff --git a/lisp/repeat.el b/lisp/repeat.el
@@ -384,14 +384,14 @@ When non-nil, and the last typed key (with or without modifiers)
 doesn't exist in the keymap specified by the `repeat-map' property
 of the command, don't activate that keymap for the next command.
 Thus, when this is non-nil, only the same keys among repeatable
-keys are allowed in the repeating sequence. For example, with a
+keys are allowed in the repeating sequence.  For example, with a
 non-nil value, only \\`C-x u u' repeats undo, whereas \\`C-/ u' doesn't.
 
 You can also set the property `repeat-check-key' on the command symbol.
 This property can override the value of this variable.
 When the variable value is non-nil, but the property value is `no',
 then don't check the last key.  Also when the variable value is nil,
-but the property value is `t', then check the last key."
+but the property value is t, then check the last key."
   :type 'boolean
   :group 'repeat
   :version "28.1")
diff --git a/lisp/saveplace.el b/lisp/saveplace.el
@@ -151,7 +151,7 @@ different hosts.
 Changing this option requires rewriting `save-place-alist' with
 corresponding file name format, therefore setting this option
 just using `setq' may cause out-of-sync problems.  You should use
-either `setopt' or M-x customize-variable to set this option."
+either `setopt' or \\[customize-variable] to set this option."
   :type 'boolean
   :set (lambda (sym val)
          (set-default sym val)
diff --git a/lisp/select.el b/lisp/select.el
@@ -153,7 +153,7 @@ systems that support it, save the selection timestamp too."
 (defun gui--clipboard-selection-unchanged-p (text)
   "Check whether the clipboard selection has changed.
 Compare the selection text, passed as argument, with the text
-from the last saved selection. For window systems that support
+from the last saved selection.  For window systems that support
 it, compare the selection timestamp too."
   (and
    (equal text gui--last-selected-text-clipboard)
diff --git a/lisp/ses.el b/lisp/ses.el
@@ -649,8 +649,8 @@ for safety.  This is a macro to prevent propagate-on-load viruses."
   t)
 
 (defmacro ses-header-row (row)
-  "Load the header row from the spreadsheet file and check it
-for safety.  This is a macro to prevent propagate-on-load viruses."
+  "Load the header row from the spreadsheet file and check it for safety.
+This is a macro to prevent propagate-on-load viruses."
   (or (and (wholenump row) (or (zerop ses--numrows) (< row ses--numrows)))
       (error "Bad header-row"))
   (setq ses--header-row row)
diff --git a/lisp/simple.el b/lisp/simple.el
@@ -8652,7 +8652,7 @@ are interchanged."
   (transpose-subr 'forward-word arg))
 
 (defun transpose-sexps-default-function (arg)
-  "Default method to locate a pair of points for transpose-sexps."
+  "Default method to locate a pair of points for `transpose-sexps'."
   ;; Here we should try to simulate the behavior of
   ;; (cons (progn (forward-sexp x) (point))
   ;;       (progn (forward-sexp (- x)) (point)))
@@ -10733,10 +10733,10 @@ option's default value is set to t, so that Backspace can be used
 to delete backward, and Delete can be used to delete forward.
 
 If not running under a window system, customizing this option
-accomplishes a similar effect by mapping C-h, which is usually
-generated by the Backspace key, to DEL, and by mapping DEL to C-d
-via `keyboard-translate'.  The former functionality of C-h is
-available on the F1 key.  You should probably not use this
+accomplishes a similar effect by mapping \\`C-h', which is usually
+generated by the Backspace key, to \\`DEL', and by mapping \\`DEL' to
+\\`C-d' via `keyboard-translate'.  The former functionality of \\`C-h'
+is available on the F1 key.  You should probably not use this
 setting if you don't have both Backspace, Delete and F1 keys.
 
 Setting this variable with setq doesn't take effect.  Programmatically,
@@ -10779,27 +10779,27 @@ call `normal-erase-is-backspace-mode' (which see) instead."
 (define-minor-mode normal-erase-is-backspace-mode
   "Toggle the Erase and Delete mode of the Backspace and Delete keys.
 
-On window systems, when this mode is on, Delete is mapped to C-d
-and Backspace is mapped to DEL; when this mode is off, both
-Delete and Backspace are mapped to DEL.  (The remapping goes via
+On window systems, when this mode is on, Delete is mapped to \\`C-d'
+and Backspace is mapped to \\`DEL'; when this mode is off, both
+Delete and Backspace are mapped to \\`DEL'.  (The remapping goes via
 `local-function-key-map', so binding Delete or Backspace in the
 global or local keymap will override that.)
 
 In addition, on window systems, the bindings of C-Delete, M-Delete,
 C-M-Delete, C-Backspace, M-Backspace, and C-M-Backspace are changed in
 the global keymap in accordance with the functionality of Delete and
-Backspace.  For example, if Delete is remapped to C-d, which deletes
+Backspace.  For example, if Delete is remapped to \\`C-d', which deletes
 forward, C-Delete is bound to `kill-word', but if Delete is remapped
-to DEL, which deletes backward, C-Delete is bound to
+to \\`DEL', which deletes backward, C-Delete is bound to
 `backward-kill-word'.
 
 If not running on a window system, a similar effect is accomplished by
-remapping C-h (normally produced by the Backspace key) and DEL via
-`keyboard-translate': if this mode is on, C-h is mapped to DEL and DEL
-to C-d; if it's off, the keys are not remapped.
+remapping \\`C-h' (normally produced by the Backspace key) and \\`DEL'
+via `keyboard-translate': if this mode is on, \\`C-h' is mapped to
+\\`DEL' and \\`DEL' to \\`C-d'; if it's off, the keys are not remapped.
 
 When not running on a window system, and this mode is turned on, the
-former functionality of C-h is available on the F1 key.  You should
+former functionality of \\`C-h' is available on the F1 key.  You should
 probably not turn on this mode on a text-only terminal if you don't
 have both Backspace, Delete and F1 keys.
 
diff --git a/lisp/sqlite-mode.el b/lisp/sqlite-mode.el
@@ -42,7 +42,7 @@
   "DEL" #'sqlite-mode-delete)
 
 (define-derived-mode sqlite-mode special-mode "Sqlite"
-  "This mode lists the contents of an .sqlite3 file"
+  "This mode lists the contents of an .sqlite3 file."
   :interactive nil
   (buffer-disable-undo)
   (setq-local buffer-read-only t
diff --git a/lisp/tempo.el b/lisp/tempo.el
@@ -119,7 +119,7 @@ user for text to insert in the templates."
   :type 'boolean)
 
 (defcustom tempo-insert-region nil
-  "Automatically insert current region when there is a `r' in the template
+  "Automatically insert current region when there is a `r' in the template.
 If this variable is nil, `r' elements will be treated just like `p'
 elements, unless the template function is given a prefix (or a non-nil
 argument).  If this variable is non-nil, the behavior is reversed.
diff --git a/lisp/term.el b/lisp/term.el
