master dd1220b: ; More stylistic docfixes in emacs-lisp/*.el found by checkdoc

[Stefan Kangas]

branch: master
commit dd1220b96972d77e5bbe1094586514bae63fe1eb
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    ; More stylistic docfixes in emacs-lisp/*.el found by checkdoc
---
 lisp/emacs-lisp/advice.el     |  4 ++--
 lisp/emacs-lisp/autoload.el   |  6 +++---
 lisp/emacs-lisp/backtrace.el  |  2 +-
 lisp/emacs-lisp/byte-opt.el   |  4 ++--
 lisp/emacs-lisp/byte-run.el   | 10 +++++-----
 lisp/emacs-lisp/bytecomp.el   |  4 ++--
 lisp/emacs-lisp/checkdoc.el   |  2 +-
 lisp/emacs-lisp/cl-generic.el |  2 +-
 lisp/emacs-lisp/comp.el       |  2 +-
 lisp/emacs-lisp/debug.el      | 14 +++++++-------
 lisp/emacs-lisp/derived.el    |  2 +-
 lisp/emacs-lisp/edebug.el     |  4 ++--
 lisp/emacs-lisp/eieio-base.el |  2 +-
 lisp/emacs-lisp/elint.el      |  2 +-
 lisp/emacs-lisp/ert.el        |  4 ++--
 lisp/emacs-lisp/ewoc.el       |  2 +-
 lisp/emacs-lisp/generator.el  |  2 +-
 lisp/emacs-lisp/lisp-mode.el  |  2 +-
 lisp/emacs-lisp/nadvice.el    |  2 +-
 lisp/emacs-lisp/testcover.el  |  2 +-
 20 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el
index 1f276c7..15e413e 100644
--- a/lisp/emacs-lisp/advice.el
+++ b/lisp/emacs-lisp/advice.el
@@ -1033,7 +1033,7 @@
 ;;
 ;; To make sure a certain piece of advice gets executed even if some error or
 ;; non-local exit occurred in any preceding code, we can protect it by using
-;; the `protect' keyword. (if any of the around advices is protected then the
+;; the `protect' keyword (if any of the around advices is protected then the
 ;; whole around advice onion will be protected):
 ;;
 ;; (defadvice foo (after fg-cleanup prot act)
@@ -3105,7 +3105,7 @@ The syntax of `defadvice' is as follows:
 FUNCTION ::= Name of the function to be advised.
 CLASS ::= `before' | `around' | `after' | `activation' | `deactivation'.
 NAME ::= Non-nil symbol that names this piece of advice.
-POSITION ::= `first' | `last' | NUMBER. Optional, defaults to `first',
+POSITION ::= `first' | `last' | NUMBER.  Optional, defaults to `first',
     see also `ad-add-advice'.
 ARGLIST ::= An optional argument list to be used for the advised function
     instead of the argument list of the original.  The first one found in
diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el
index e9a2063..38512e0 100644
--- a/lisp/emacs-lisp/autoload.el
+++ b/lisp/emacs-lisp/autoload.el
@@ -25,7 +25,7 @@
 
 ;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
 ;; date.  It interprets magic cookies of the form ";;;###autoload" in
-;; lisp source files in various useful ways.  To learn more, read the
+;; Lisp source files in various useful ways.  To learn more, read the
 ;; source; if you're going to use this, you'd better be able to.
 
 ;;; Code:
@@ -432,8 +432,8 @@ FILE's name."
   file)
 
 (defun autoload-insert-section-header (outbuf autoloads load-name file time)
-  "Insert the section-header line,
-which lists the file name and which functions are in it, etc."
+  "Insert the section-header line.
+This lists the file name and which functions are in it, etc."
   ;; (cl-assert ;Make sure we don't insert it in the middle of another section.
   ;;  (save-excursion
   ;;    (or (not (re-search-backward
diff --git a/lisp/emacs-lisp/backtrace.el b/lisp/emacs-lisp/backtrace.el
index ea70baa..a5721aa 100644
--- a/lisp/emacs-lisp/backtrace.el
+++ b/lisp/emacs-lisp/backtrace.el
@@ -868,7 +868,7 @@ commands.
 \\{backtrace-mode-map}
 
 A mode which inherits from Backtrace mode, or a command which
-creates a backtrace-mode buffer, should usually do the following:
+creates a `backtrace-mode' buffer, should usually do the following:
 
  - Set `backtrace-revert-hook', if the buffer contents need
    to be specially recomputed prior to `revert-buffer'.
diff --git a/lisp/emacs-lisp/byte-opt.el b/lisp/emacs-lisp/byte-opt.el
index 966ef26..c15814a 100644
--- a/lisp/emacs-lisp/byte-opt.el
+++ b/lisp/emacs-lisp/byte-opt.el
@@ -202,7 +202,7 @@
                          (intern (substring (symbol-name arg) 5))
                        arg)
                    (if (integerp (setq c (car arg)))
-                       (error "non-symbolic byte-op %s" c))
+                        (error "Non-symbolic byte-op %s" c))
                    (if (eq c 'TAG)
                        (setq c arg)
                      (setq a (cond ((memq c byte-goto-ops)
@@ -1753,7 +1753,7 @@ See Info node `(elisp) Integer Basics'."
               (setq tags (delq tmp tags))
               (setq rest (cdr rest))))
        (setq rest (cdr rest))))
-    (if tags (error "optimizer error: missed tags %s" tags))
+    (if tags (error "Optimizer error: missed tags %s" tags))
     ;; Remove addrs, lap = ( [ (op . arg) | (TAG tagno) ]* )
     (mapcar (lambda (elt)
               (if (numberp elt)
diff --git a/lisp/emacs-lisp/byte-run.el b/lisp/emacs-lisp/byte-run.el
index 6d698ff..35c80e5 100644
--- a/lisp/emacs-lisp/byte-run.el
+++ b/lisp/emacs-lisp/byte-run.el
@@ -529,11 +529,11 @@ is enabled."
   (list 'quote (eval (cons 'progn body) lexical-binding)))
 
 (defmacro eval-and-compile (&rest body)
-  "Like `progn', but evaluates the body at compile time and at
-load time.  In interpreted code, this is entirely equivalent to
-`progn', except that the value of the expression may be (but is
-not necessarily) computed at load time if eager macro expansion
-is enabled."
+  "Like `progn', but evaluates the body at compile time and at load time.
+In interpreted code, this is entirely equivalent to `progn',
+except that the value of the expression may be (but is not
+necessarily) computed at load time if eager macro expansion is
+enabled."
   (declare (debug (&rest def-form)) (indent 0))
   ;; When the byte-compiler expands code, this macro is not used, so we're
   ;; either about to run `body' (plain interpretation) or we're doing eager
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 776e84d..8a73061 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -915,7 +915,7 @@ CONST2 may be evaluated multiple times."
                                ,bytes ,pc))
 
 (defun byte-compile-lapcode (lap)
-  "Turns lapcode into bytecode.  The lapcode is destroyed."
+  "Turn lapcode into bytecode.  The lapcode is destroyed."
   ;; Lapcode modifications: changes the ID of a tag to be the tag's PC.
   (let ((pc 0)                 ; Program counter
        op off                  ; Operation & offset
@@ -1899,7 +1899,7 @@ also be compiled."
   "Non-nil to prevent byte-compiling of Emacs Lisp code.
 This is normally set in local file variables at the end of the elisp file:
 
-\;; Local Variables:\n;; no-byte-compile: t\n;; End: ") ;Backslash for 
compile-main.
+\;; Local Variables:\n;; no-byte-compile: t\n;; End:") ;Backslash for 
compile-main.
 ;;;###autoload(put 'no-byte-compile 'safe-local-variable 'booleanp)
 
 (defun byte-recompile-file (filename &optional force arg load)
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 3ed489f..9a37941 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -2081,7 +2081,7 @@ If the offending word is in a piece of quoted text, then 
it is skipped."
                      (not (thing-at-point-looking-at
                            help-xref-url-regexp)))
                 (if (checkdoc-autofix-ask-replace
-                     b e (format "Text %s should be capitalized.  Fix? "
+                     b e (format "Text %s should be capitalized.  Fix?"
                                  text)
                      (capitalize text) t)
                     nil
diff --git a/lisp/emacs-lisp/cl-generic.el b/lisp/emacs-lisp/cl-generic.el
index 4a69df1..1640975 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -960,7 +960,7 @@ Can only be used from within the lexical body of a primary 
or around method."
 ;;; Add support for describe-function
 
 (defun cl--generic-search-method (met-name)
-  "For `find-function-regexp-alist'.  Searches for a cl-defmethod.
+  "For `find-function-regexp-alist'.  Search for a `cl-defmethod'.
 MET-NAME is as returned by `cl--generic-load-hist-format'."
   (let ((base-re (concat "(\\(?:cl-\\)?defmethod[ \t]+"
                          (regexp-quote (format "%s" (car met-name)))
diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el
index bb13545..ab36b8a 100644
--- a/lisp/emacs-lisp/comp.el
+++ b/lisp/emacs-lisp/comp.el
@@ -3804,7 +3804,7 @@ Return the trampoline if found or nil otherwise."
 
 ;;;###autoload
 (defun comp-clean-up-stale-eln (file)
-  "Given FILE remove all its *.eln files in `native-comp-eln-load-path'
+  "Given FILE remove all its *.eln files in `native-comp-eln-load-path'.
 sharing the original source filename (including FILE)."
   (when (string-match (rx "-" (group-n 1 (1+ hex)) "-" (1+ hex) ".eln" eos)
                       file)
diff --git a/lisp/emacs-lisp/debug.el b/lisp/emacs-lisp/debug.el
index 8da9fb7..0592db8 100644
--- a/lisp/emacs-lisp/debug.el
+++ b/lisp/emacs-lisp/debug.el
@@ -119,7 +119,7 @@ This is to optimize `debugger-make-xrefs'.")
 (defvar debugger-jumping-flag nil
   "Non-nil means that `debug-on-entry' is disabled.
 This variable is used by `debugger-jump', `debugger-step-through',
-and `debugger-reenable' to temporarily disable debug-on-entry.")
+and `debugger-reenable' to temporarily disable `debug-on-entry'.")
 
 (defvar inhibit-trace)                  ;Not yet implemented.
 
@@ -128,7 +128,7 @@ and `debugger-reenable' to temporarily disable 
debug-on-entry.")
 It is a list expected to take the form (CAUSE . REST)
 where CAUSE can be:
 - debug: called for entry to a flagged function.
-- t: called because of debug-on-next-call.
+- t: called because of `debug-on-next-call'.
 - lambda: same thing but via `funcall'.
 - exit: called because of exit of a flagged function.
 - error: called because of `debug-on-error'.")
@@ -335,7 +335,7 @@ Make functions into cross-reference buttons if DO-XREFS is 
non-nil."
 
 (defun debugger-setup-buffer (args)
   "Initialize the `*Backtrace*' buffer for entry to the debugger.
-That buffer should be current already and in debugger-mode."
+That buffer should be current already and in `debugger-mode'."
   (setq backtrace-frames (nthcdr
                           ;; Remove debug--implement-debug-on-entry and the
                           ;; advice's `apply' frame.
@@ -454,7 +454,7 @@ will be used, such as in a debug on exit from a frame."
   (exit-recursive-edit))
 
 (defun debugger-jump ()
-  "Continue to exit from this frame, with all debug-on-entry suspended."
+  "Continue to exit from this frame, with all `debug-on-entry' suspended."
   (interactive)
   (debugger-frame)
   (setq debugger-jumping-flag t)
@@ -464,7 +464,7 @@ will be used, such as in a debug on exit from a frame."
   (exit-recursive-edit))
 
 (defun debugger-reenable ()
-  "Turn all debug-on-entry functions back on.
+  "Turn all `debug-on-entry' functions back on.
 This function is put on `post-command-hook' by `debugger-jump' and
 removes itself from that hook."
   (setq debugger-jumping-flag nil)
@@ -695,7 +695,7 @@ Redefining FUNCTION also cancels it."
 ;;;###autoload
 (defun cancel-debug-on-entry (&optional function)
   "Undo effect of \\[debug-on-entry] on FUNCTION.
-If FUNCTION is nil, cancel debug-on-entry for all functions.
+If FUNCTION is nil, cancel `debug-on-entry' for all functions.
 When called interactively, prompt for FUNCTION in the minibuffer.
 To specify a nil argument interactively, exit with an empty minibuffer."
   (interactive
@@ -798,7 +798,7 @@ another symbol also cancels it."
 ;;;###autoload
 (defun cancel-debug-on-variable-change (&optional variable)
   "Undo effect of \\[debug-on-variable-change] on VARIABLE.
-If VARIABLE is nil, cancel debug-on-variable-change for all variables.
+If VARIABLE is nil, cancel `debug-on-variable-change' for all variables.
 When called interactively, prompt for VARIABLE in the minibuffer.
 To specify a nil argument interactively, exit with an empty minibuffer."
   (interactive
diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el
index 43d6dfd..5e9644d 100644
--- a/lisp/emacs-lisp/derived.el
+++ b/lisp/emacs-lisp/derived.el
@@ -139,7 +139,7 @@ KEYWORD-ARGS:
                    A nil value means to simply use the same abbrev-table
                    as the parent.
            :after-hook FORM
-                   A single lisp form which is evaluated after the mode
+                   A single Lisp form which is evaluated after the mode
                    hooks have been run.  It should not be quoted.
            :interactive BOOLEAN
                    Whether the derived mode should be `interactive' or not.
diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index 7def9ff..4f3c05b 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -3571,7 +3571,7 @@ This is useful for exiting even if `unwind-protect' code 
may be executed."
 (defun edebug-set-initial-mode ()
   "Set the initial execution mode of Edebug.
 The mode is requested via the key that would be used to set the mode in
-edebug-mode."
+`edebug-mode'."
   (interactive)
   (let* ((old-mode edebug-initial-mode)
         (key (read-key-sequence
@@ -4468,7 +4468,7 @@ With prefix argument, make it a temporary breakpoint."
               'read-expression-history)))))))
   (edebug-modify-breakpoint t condition arg))
 
-(easy-menu-define edebug-menu edebug-mode-map "Edebug menus" edebug-mode-menus)
+(easy-menu-define edebug-menu edebug-mode-map "Edebug menus." 
edebug-mode-menus)
 
 
 ;;; Finalize Loading
diff --git a/lisp/emacs-lisp/eieio-base.el b/lisp/emacs-lisp/eieio-base.el
index ec7c899..5414c32 100644
--- a/lisp/emacs-lisp/eieio-base.el
+++ b/lisp/emacs-lisp/eieio-base.el
@@ -252,7 +252,7 @@ This is used with the `object-write' method.")
               :documentation
               "Saving this object should make backup files.
 Setting to nil will mean no backups are made."))
-  "This special class enables persistence through save files
+  "This special class enables persistence through save files.
 Use the `object-write' method to write this object to disk.  The save
 format is Emacs Lisp code which calls the constructor for the saved
 object.  For this reason, only slots which do not have an `:initarg'
diff --git a/lisp/emacs-lisp/elint.el b/lisp/emacs-lisp/elint.el
index 0fba593..32b2cbd 100644
--- a/lisp/emacs-lisp/elint.el
+++ b/lisp/emacs-lisp/elint.el
@@ -1035,7 +1035,7 @@ Insert HEADER followed by a blank line if non-nil."
     (sit-for 0)))
 
 (defun elint-set-mode-line (&optional on)
-  "Set the mode-line-process of the Elint log buffer."
+  "Set the `mode-line-process' of the Elint log buffer."
   (with-current-buffer (elint-get-log-buffer)
     (and (eq major-mode 'compilation-mode)
         (setq mode-line-process
diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index 92acfe7..d4d8510 100644
--- a/lisp/emacs-lisp/ert.el
+++ b/lisp/emacs-lisp/ert.el
@@ -1958,9 +1958,9 @@ non-nil, returns the face for expected results.."
   nil)
 
 (defun ert--results-font-lock-function (enabledp)
-  "Redraw the ERT results buffer after font-lock-mode was switched on or off.
+  "Redraw the ERT results buffer after `font-lock-mode' was switched on or off.
 
-ENABLEDP is true if font-lock-mode is switched on, false
+ENABLEDP is true if `font-lock-mode' is switched on, false
 otherwise."
   (ert--results-update-ewoc-hf ert--results-ewoc ert--results-stats)
   (ewoc-refresh ert--results-ewoc)
diff --git a/lisp/emacs-lisp/ewoc.el b/lisp/emacs-lisp/ewoc.el
index ca29b6d..68f94ed 100644
--- a/lisp/emacs-lisp/ewoc.el
+++ b/lisp/emacs-lisp/ewoc.el
@@ -147,7 +147,7 @@ and (ewoc--node-nth dll -1) returns the last node."
   buffer pretty-printer header footer dll last-node hf-pp)
 
 (defmacro ewoc--set-buffer-bind-dll-let* (ewoc varlist &rest forms)
-  "Execute FORMS with ewoc--buffer selected as current buffer,
+  "Execute FORMS with `ewoc--buffer' selected as current buffer,
 `dll' bound to the dll, and VARLIST bound as in a let*.
 `dll' will be bound when VARLIST is initialized, but
 the current buffer will *not* have been changed.
diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el
index 2acf939..7801fc9 100644
--- a/lisp/emacs-lisp/generator.el
+++ b/lisp/emacs-lisp/generator.el
@@ -668,7 +668,7 @@ sub-iterator function returns via `iter-end-of-sequence'."
          (iter-close ,valsym)))))
 
 (defmacro iter-defun (name arglist &rest body)
-  "Creates a generator NAME.
+  "Create a generator NAME.
 When called as a function, NAME returns an iterator value that
 encapsulates the state of a computation that produces a sequence
 of values.  Callers can retrieve each value using `iter-next'."
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index b3b1efc..eac3c03 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -627,7 +627,7 @@ Value for `adaptive-fill-function'."
 ;; encouraged to use 'lisp-data-mode' instead.
 (defun lisp-mode-variables (&optional lisp-syntax keywords-case-insensitive
                                       elisp)
-  "Common initialization routine for lisp modes.
+  "Common initialization routine for Lisp modes.
 The LISP-SYNTAX argument is used by code in inf-lisp.el and is
 \(uselessly) passed from pp.el, chistory.el, gnus-kill.el and
 score-mode.el.  KEYWORDS-CASE-INSENSITIVE non-nil means that for
diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el
index a2a5aae..8fc2986 100644
--- a/lisp/emacs-lisp/nadvice.el
+++ b/lisp/emacs-lisp/nadvice.el
@@ -160,7 +160,7 @@ Each element has the form (WHERE BYTECODE STACK) where:
    (t (eval spec))))
 
 (defun advice--interactive-form (function)
-  ;; Like `interactive-form' but tries to avoid autoloading functions.
+  "Like `interactive-form' but tries to avoid autoloading functions."
   (when (commandp function)
     (if (not (and (symbolp function) (autoloadp (indirect-function function))))
         (interactive-form function)
diff --git a/lisp/emacs-lisp/testcover.el b/lisp/emacs-lisp/testcover.el
index f5a624b..cdd966e 100644
--- a/lisp/emacs-lisp/testcover.el
+++ b/lisp/emacs-lisp/testcover.el
@@ -333,7 +333,7 @@ vectors as well as conses."
 ;;;=========================================================================
 
 (defun testcover-mark (def)
-  "Marks one DEF (a function or macro symbol) to highlight its contained forms
+  "Mark one DEF (a function or macro symbol) to highlight its contained forms
 that did not get completely tested during coverage tests.
   A marking with the face `testcover-nohits' (default = red) indicates that the
 form was never evaluated.  A marking using the `testcover-1value' face