; More minor docfixes found by checkdoc

24 files changed, 119 insertions, 117 deletions

diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el
index 8e8d0e22651..1f276c7f7a3 100644
--- a/lisp/emacs-lisp/advice.el
+++ b/lisp/emacs-lisp/advice.el
@@ -36,12 +36,12 @@
 ;; @ Introduction:
 ;; ===============
 ;; This package implements a full-fledged Lisp-style advice mechanism
-;; for Emacs Lisp. Advice is a clean and efficient way to modify the
+;; for Emacs Lisp.  Advice is a clean and efficient way to modify the
 ;; behavior of Emacs Lisp functions without having to keep  personal
-;; modified copies of such functions around. A great number of such
+;; modified copies of such functions around.  A great number of such
 ;; modifications can be achieved by treating the original function as a
 ;; black box and specifying a different execution environment for it
-;; with a piece of advice. Think of a piece of advice as a kind of fancy
+;; with a piece of advice.  Think of a piece of advice as a kind of fancy
 ;; hook that you can attach to any function/macro/subr.
 
 ;; @ Highlights:
@@ -95,7 +95,7 @@
 ;; @ Restrictions:
 ;; ===============
 ;; - Advised functions/macros/subrs will only exhibit their advised behavior
-;;   when they are invoked via their function cell. This means that advice will
+;;   when they are invoked via their function cell.  This means that advice will
 ;;   not work for the following:
 ;;   + advised subrs that are called directly from other subrs or C-code
 ;;   + advised subrs that got replaced with their byte-code during
@@ -107,7 +107,7 @@
 ;; ==========
 ;; This package is an extension and generalization of packages such as
 ;; insert-hooks.el written by Noah S. Friedman, and advise.el written by
-;; Raul J. Acevedo. Some ideas used in here come from these packages,
+;; Raul J. Acevedo.  Some ideas used in here come from these packages,
 ;; others come from the various Lisp advice mechanisms I've come across
 ;; so far, and a few are simply mine.
 
@@ -235,10 +235,10 @@
 ;; found in the list of before/around/after advices will be used.
 
 ;; <flags> is a list of symbols that specify further information about the
-;; advice. All flags can be specified with unambiguous initial substrings.
+;; advice.  All flags can be specified with unambiguous initial substrings.
 ;;   `activate': Specifies that the advice information of the advised
 ;;              function should be activated right after this advice has been
-;;              defined. In forward advices `activate' will be ignored.
+;;              defined.  In forward advices `activate' will be ignored.
 ;;   `protect': Specifies that this advice should be protected against
 ;;              non-local exits and errors in preceding code/advices.
 ;;   `compile': Specifies that the advised function should be byte-compiled.
@@ -347,7 +347,7 @@
 ;; argument list redefinition given in a piece of advice.  While this simple
 ;; method might be sufficient in many cases, it has the disadvantage that it
 ;; is not very portable because it hardcodes the argument names into the
-;; advice. If the definition of the original function changes the advice
+;; advice.  If the definition of the original function changes the advice
 ;; might break even though the code might still be correct.  Situations like
 ;; that arise, for example, if one advises a subr like `eval-region' which
 ;; gets redefined in a non-advice style into a function by the edebug
@@ -443,7 +443,7 @@
 ;; of the advised function we need a mapping mechanism that maps this
 ;; argument list onto that of the original function.  Hence SYM and
 ;; NEWDEF have to be properly mapped onto the &rest variable when the
-;; original definition is called. Advice automatically takes care of
+;; original definition is called.  Advice automatically takes care of
 ;; that mapping, hence, the advice programmer can specify an argument
 ;; list without having to know about the exact structure of the
 ;; original argument list as long as the new argument list takes a
@@ -467,7 +467,7 @@
 ;; The advised definition will get compiled either if `ad-activate' was called
 ;; interactively with a prefix argument, or called explicitly with its second
 ;; argument as t, or, if `ad-default-compilation-action' justifies it according
-;; to the current system state. If the advised definition was
+;; to the current system state.  If the advised definition was
 ;; constructed during "preactivation" (see below) then that definition will
 ;; be already compiled because it was constructed during byte-compilation of
 ;; the file that contained the `defadvice' with the `preactivate' flag.
@@ -707,7 +707,7 @@
 ;; @@ Adding a piece of advice with `ad-add-advice':
 ;; =================================================
 ;; The non-interactive function `ad-add-advice' can be used to add a piece of
-;; advice to some function without using `defadvice'. This is useful if advice
+;; advice to some function without using `defadvice'.  This is useful if advice
 ;; has to be added somewhere by a function (also look at `ad-make-advice').
 
 ;; @@ Activation/deactivation advices, file load hooks:
@@ -739,7 +739,7 @@
 ;;     A piece of advice gets defined with `defadvice' and added to the
 ;;     `advice-info' property of a function.
 ;; - Enablement:
-;;     Every piece of advice has an enablement flag associated with it. Only
+;;     Every piece of advice has an enablement flag associated with it.  Only
 ;;     enabled advices are considered during construction of an advised
 ;;     definition.
 ;; - Activation:
@@ -808,9 +808,9 @@
 ;;                     argument access text macros to get/set the values of
 ;;                     actual arguments at a certain position
 ;;   ad-arg-bindings   text macro that returns the actual names, values
-;;                     and types of the arguments as a list of bindings. The
+;;                     and types of the arguments as a list of bindings.  The
 ;;                     order of the bindings corresponds to the order of the
-;;                     arguments. The individual fields of every binding (name,
+;;                     arguments.  The individual fields of every binding (name,
 ;;                     value and type) can be accessed with the function
 ;;                     `ad-arg-binding-field' (see example above).
 ;;   ad-do-it          text macro that identifies the place where the original
@@ -839,20 +839,20 @@
 ;; use the macro `defadvice' which takes a function name, a list of advice
 ;; specifiers and a list of body forms as arguments.  The first element of
 ;; the advice specifiers is the class of the advice, the second is its name,
-;; the third its position and the rest are some flags. The class of our
+;; the third its position and the rest are some flags.  The class of our
 ;; first advice is `before', its name is `fg-add2', its position among the
 ;; currently defined before advices (none so far) is `first', and the advice
-;; will be `activate'ed immediately. Advice names are global symbols, hence,
-;; the name space conventions used for function names should be applied. All
+;; will be `activate'ed immediately.  Advice names are global symbols, hence,
+;; the name space conventions used for function names should be applied.  All
 ;; advice names in this tutorial will be prefixed with `fg' for `Foo Games'
 ;; (because everybody has the right to be inconsistent all the function names
 ;; used in this tutorial do NOT follow this convention).
 ;;
 ;; In the body of an advice we can refer to the argument variables of the
-;; original function by name. Here we add 1 to X so the effect of calling
+;; original function by name.  Here we add 1 to X so the effect of calling
 ;; `foo' will be to actually add 2. All of the advice definitions below only
 ;; have one body form for simplicity, but there is no restriction to that
-;; extent. Every piece of advice can have a documentation string which will
+;; extent.  Every piece of advice can have a documentation string which will
 ;; be combined with the documentation of the original function.
 ;;
 ;; (defadvice foo (before fg-add2 first activate)
@@ -866,11 +866,11 @@
 ;; @@ Specifying the position of an advice:
 ;; ========================================
 ;; Now we define the second before advice which will cancel the effect of
-;; the previous advice. This time we specify the position as 0 which is
-;; equivalent to `first'. A number can be used to specify the zero-based
-;; position of an advice among the list of advices in the same class. This
+;; the previous advice.  This time we specify the position as 0 which is
+;; equivalent to `first'.  A number can be used to specify the zero-based
+;; position of an advice among the list of advices in the same class.  This
 ;; time we already have one before advice hence the position specification
-;; actually has an effect. So, after the following definition the position
+;; actually has an effect.  So, after the following definition the position
 ;; of the previous advice will be 1 even though we specified it with `first'
 ;; above, the reason for this is that the position argument is relative to
 ;; the currently defined pieces of advice which by now has changed.
@@ -886,7 +886,7 @@
 ;; @@ Redefining a piece of advice:
 ;; ================================
 ;; Now we define an advice with the same class and same name but with a
-;; different position. Defining an advice in a class in which an advice with
+;; different position.  Defining an advice in a class in which an advice with
 ;; that name already exists is interpreted as a redefinition of that
 ;; particular advice, in which case the position argument will be ignored
 ;; and the previous position of the redefined piece of advice is used.
@@ -919,7 +919,7 @@
 ;; =================================
 ;; We can make a function interactive (or change its interactive behavior)
 ;; by specifying an interactive form in one of the before or around
-;; advices (there could also be body forms in this advice). The particular
+;; advices (there could also be body forms in this advice).  The particular
 ;; definition always assigns 5 as an argument to X which gives us 6 as a
 ;; result when we call foo interactively:
 ;;
@@ -945,13 +945,13 @@
 ;;
 ;; @@ Around advices:
 ;; ==================
-;; Now we'll try some `around' advices. An around advice is a wrapper around
-;; the original definition. It can shadow or establish bindings for the
+;; Now we'll try some `around' advices.  An around advice is a wrapper around
+;; the original definition.  It can shadow or establish bindings for the
 ;; original definition, and it can look at and manipulate the value returned
-;; by the original function. The position of the special keyword `ad-do-it'
-;; specifies where the code of the original function will be executed. The
+;; by the original function.  The position of the special keyword `ad-do-it'
+;; specifies where the code of the original function will be executed.  The
 ;; keyword can appear multiple times which will result in multiple calls of
-;; the original function in the resulting advised code. Note, that if we don't
+;; the original function in the resulting advised code.  Note, that if we don't
 ;; specify a position argument (i.e., `first', `last' or a number), then
 ;; `first' (or 0) is the default):
 ;;
@@ -967,7 +967,7 @@
 ;; Around advices are assembled like onion skins where the around advice
 ;; with position 0 is the outermost skin and the advice at the last position
 ;; is the innermost skin which is directly wrapped around the call of the
-;; original definition of the function. Hence, after the next `defadvice' we
+;; original definition of the function.  Hence, after the next `defadvice' we
 ;; will first multiply X by 2 then add 1 and then call the original
 ;; definition (i.e., add 1 again):
 ;;
@@ -984,8 +984,8 @@
 ;; =================================
 ;; In every `defadvice' so far we have used the flag `activate' to activate
 ;; the advice immediately after its definition, and that's what we want in
-;; most cases. However, if we define multiple pieces of advice for a single
-;; function then activating every advice immediately is inefficient. A
+;; most cases.  However, if we define multiple pieces of advice for a single
+;; function then activating every advice immediately is inefficient.  A
 ;; better way to do this is to only activate the last defined advice.
 ;; For example:
 ;;
@@ -1077,7 +1077,7 @@
 ;; neutralize the effect of the advice of one of the packages.
 ;;
 ;; The following disables the after advice `fg-times-x' in the function `foo'.
-;; All that does is to change a flag for this particular advice. All the
+;; All that does is to change a flag for this particular advice.  All the
 ;; other information defining it will be left unchanged (e.g., its relative
 ;; position in this advice class, etc.).
 ;;
@@ -1094,9 +1094,9 @@
 ;; 24
 ;;
 ;; If we want to disable all multiplication advices in `foo' we can use a
-;; regular expression that matches the names of such advices. Actually, any
+;; regular expression that matches the names of such advices.  Actually, any
 ;; advice name that contains a match for the regular expression will be
-;; called a match. A special advice class `any' can be used to consider
+;; called a match.  A special advice class `any' can be used to consider
 ;; all advice classes:
 ;;
 ;; (ad-disable-advice 'foo 'any "^fg-.*times")
@@ -1122,7 +1122,7 @@
 ;; 9
 ;;
 ;; The following will activate all currently active advised functions that
-;; contain some advice matched by the regular expression. This is a save
+;; contain some advice matched by the regular expression.  This is a save
 ;; way to update the activation of advised functions whose advice changed
 ;; in some way or other without accidentally also activating currently
 ;; inactive functions:
@@ -1136,7 +1136,7 @@
 ;;
 ;; Another use for the dis/enablement mechanism is to define a piece of advice
 ;; and keep it "dormant" until a particular condition is satisfied, i.e., until
-;; then the advice will not be used during activation. The `disable' flag lets
+;; then the advice will not be used during activation.  The `disable' flag lets
 ;; one do that with `defadvice':
 ;;
 ;; (defadvice foo (before fg-1-more dis)
@@ -1165,7 +1165,7 @@
 ;; ===========
 ;; Advised definitions get cached to allow efficient activation/deactivation
 ;; without having to reconstruct them if nothing in the advice-info of a
-;; function has changed. The following idiom can be used to temporarily
+;; function has changed.  The following idiom can be used to temporarily
 ;; deactivate functions that have a piece of advice defined by a certain
 ;; package (we save the old definition to check out caching):
 ;;
@@ -1350,9 +1350,9 @@
 ;; @@ Portable argument access:
 ;; ============================
 ;; So far, we always used the actual argument variable names to access an
-;; argument in a piece of advice. For many advice applications this is
-;; perfectly ok and keeps advices simple. However, it decreases portability
-;; of advices because it assumes specific argument variable names. For example,
+;; argument in a piece of advice.  For many advice applications this is
+;; perfectly ok and keeps advices simple.  However, it decreases portability
+;; of advices because it assumes specific argument variable names.  For example,
 ;; if one advises a subr such as `eval-region' which then gets redefined by
 ;; some package (e.g., edebug) into a function with different argument names,
 ;; then a piece of advice written for `eval-region' that was written with
@@ -1360,7 +1360,7 @@
 ;;
 ;; Argument access text macros allow one to access arguments of an advised
 ;; function in a portable way without having to worry about all these
-;; possibilities. These macros will be translated into the proper access forms
+;; possibilities.  These macros will be translated into the proper access forms
 ;; at activation time, hence, argument access will be as efficient as if
 ;; the arguments had been used directly in the definition of the advice.
 ;;
@@ -1386,7 +1386,7 @@
 ;; (fuu 1 1 1)
 ;; 6
 ;;
-;; Now suppose somebody redefines `fuu' with a rest argument. Our advice
+;; Now suppose somebody redefines `fuu' with a rest argument.  Our advice
 ;; will still work because we used access macros (note, that automatic
 ;; advice activation is still in effect, hence, the redefinition of `fuu'
 ;; will automatically activate all its advice):
@@ -1444,9 +1444,9 @@
 ;; give it an extra argument that controls the advised code, for example, one
 ;; might want to make an interactive function sensitive to a prefix argument.
 ;; For such cases `defadvice' allows the specification of an argument list
-;; for the advised function. Similar to the redefinition of interactive
+;; for the advised function.  Similar to the redefinition of interactive
 ;; behavior, the first argument list specification found in the list of before/
-;; around/after advices will be used. Of course, the specified argument list
+;; around/after advices will be used.  Of course, the specified argument list
 ;; should be downward compatible with the original argument list, otherwise
 ;; functions that call the advised function with the original argument list
 ;; in mind will break.
@@ -1457,9 +1457,9 @@
 ;; fii
 ;;
 ;; Now we advise `fii' to use an optional second argument that controls the
-;; amount of incrementing. A list following the (optional) position
+;; amount of incrementing.  A list following the (optional) position
 ;; argument of the advice will be interpreted as an argument list
-;; specification. This means you cannot specify an empty argument list, and
+;; specification.  This means you cannot specify an empty argument list, and
 ;; why would you want to anyway?
 ;;
 ;; (defadvice fii (before fg-inc-x (x &optional incr) act)
@@ -1476,22 +1476,22 @@
 ;; @@ Advising interactive subrs:
 ;; ==============================
 ;; For the most part there is no difference between advising functions and
-;; advising subrs. There is one situation though where one might have to write
-;; slightly different advice code for subrs than for functions. This case
+;; advising subrs.  There is one situation though where one might have to write
+;; slightly different advice code for subrs than for functions.  This case
 ;; arises when one wants to access subr arguments in a before/around advice
 ;; when the arguments were determined by an interactive call to the subr.
 ;; Advice cannot determine what `interactive' form determines the interactive
 ;; behavior of the subr, hence, when it calls the original definition in an
 ;; interactive subr invocation it has to use `call-interactively' to generate
-;; the proper interactive behavior. Thus up to that call the arguments of the
-;; interactive subr will be nil. For example, the following advice for
+;; the proper interactive behavior.  Thus up to that call the arguments of the
+;; interactive subr will be nil.  For example, the following advice for
 ;; `kill-buffer' will not work in an interactive invocation...
 ;;
 ;; (defadvice kill-buffer (before fg-kill-buffer-hook first act preact comp)
 ;;   (my-before-kill-buffer-hook (ad-get-arg 0)))
 ;; kill-buffer
 ;;
-;; ...because the buffer argument will be nil in that case. The way out of
+;; ...because the buffer argument will be nil in that case.  The way out of
 ;; this dilemma is to provide an `interactive' specification that mirrors
 ;; the interactive behavior of the unadvised subr, for example, the following
 ;; will do the right thing even when `kill-buffer' is called interactively:
@@ -1508,10 +1508,10 @@
 ;; For an advised macro instead of evaluating the original definition we
 ;; use `macroexpand', that is, changing argument values and binding
 ;; environments by pieces of advice has an affect during macro expansion
-;; but not necessarily during evaluation. In particular, any side effects
+;; but not necessarily during evaluation.  In particular, any side effects
 ;; of pieces of advice will occur during macro expansion.  To also affect
 ;; the behavior during evaluation time one has to change the value of
-;; `ad-return-value' in a piece of after advice. For example:
+;; `ad-return-value' in a piece of after advice.  For example:
 ;;
 ;; (defmacro foom (x)
 ;;   `(list ,x))
@@ -1562,7 +1562,7 @@
 ;; because it allows one to influence macro expansion as well as evaluation.
 ;; In general, advising macros should be a rather rare activity anyway, in
 ;; particular, because compile-time macro expansion takes away a lot of the
-;; flexibility and effectiveness of the advice mechanism. Macros that were
+;; flexibility and effectiveness of the advice mechanism.  Macros that were
 ;; compile-time expanded before the advice was activated will of course never
 ;; exhibit the advised behavior.
 
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 47b3c82456c..776e84dfebb 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -26,7 +26,7 @@
 
 ;;; Commentary:
 
-;; The Emacs Lisp byte compiler.  This crunches lisp source into a sort
+;; The Emacs Lisp byte compiler.  This crunches Lisp source into a sort
 ;; of p-code (`lapcode') which takes up less space and can be interpreted
 ;; faster.  [`LAP' == `Lisp Assembly Program'.]
 ;; The user entry points are byte-compile-file and byte-recompile-directory.
@@ -319,7 +319,7 @@ Elements of the list may be:
   lexical     global/dynamic variables lacking a prefix.
   lexical-dynamic
               lexically bound variable declared dynamic elsewhere
-  make-local  calls to make-variable-buffer-local that may be incorrect.
+  make-local  calls to `make-variable-buffer-local' that may be incorrect.
   mapcar      mapcar called for effect.
   constants   let-binding of, or assignment to, constants/nonvariables.
   docstrings  docstrings that are too wide (longer than
@@ -3562,7 +3562,7 @@ for symbols generated by the byte compiler itself."
   "Warn if symbol VAR refers to a free variable.
 VAR must not be lexically bound.
 If optional argument ASSIGNMENT is non-nil, this is treated as an
-assignment (i.e. `setq'). "
+assignment (i.e. `setq')."
   (unless (or (not (byte-compile-warning-enabled-p 'free-vars var))
               (boundp var)
               (memq var byte-compile-bound-variables)
@@ -4335,7 +4335,7 @@ that suppresses all warnings during execution of BODY."
    (and (symbolp obj2) (macroexp-const-p obj1) (cons obj2 (eval obj1)))))
 
 (defun byte-compile--common-test (test-1 test-2)
-  "Most specific common test of `eq', `eql' and `equal'"
+  "Most specific common test of `eq', `eql' and `equal'."
   (cond ((or (eq test-1 'equal) (eq test-2 'equal)) 'equal)
         ((or (eq test-1 'eql)   (eq test-2 'eql))   'eql)
         (t                                          'eq)))
diff --git a/lisp/emacs-lisp/cconv.el b/lisp/emacs-lisp/cconv.el
index 3abbf716875..ba29e4ec85e 100644
--- a/lisp/emacs-lisp/cconv.el
+++ b/lisp/emacs-lisp/cconv.el
@@ -32,7 +32,7 @@
 ;; Here is a brief explanation how this code works.
 ;; Firstly, we analyze the tree by calling cconv-analyze-form.
 ;; This function finds all mutated variables, all functions that are suitable
-;; for lambda lifting and all variables captured by closure. It passes the tree
+;; for lambda lifting and all variables captured by closure.  It passes the tree
 ;; once, returning a list of three lists.
 ;;
 ;; Then we calculate the intersection of the first and third lists returned by
diff --git a/lisp/emacs-lisp/check-declare.el b/lisp/emacs-lisp/check-declare.el
index bec4ad92503..83a9d3ea6ae 100644
--- a/lisp/emacs-lisp/check-declare.el
+++ b/lisp/emacs-lisp/check-declare.el
@@ -119,7 +119,7 @@ don't know how to recognize (e.g. some macros)."
 (autoload 'byte-compile-arglist-signature "bytecomp")
 
 (defgroup check-declare nil
-  "Check declare-function statements."
+  "Check `declare-function' statements."
   :group 'tools)
 
 (defcustom check-declare-ext-errors nil
@@ -230,8 +230,8 @@ fset\\|\\(?:cl-\\)?defmethod\\)\\>" type)
     errlist))
 
 (defun check-declare-sort (alist)
-  "Sort a list with elements FILE (FNFILE ...).
-Returned list has elements FNFILE (FILE ...)."
+  "Sort list ALIST with elements FILE (FNFILE ...).
+Return list with elements FNFILE (FILE ...)."
   (let (file fnfile rest sort a)
     (dolist (e alist)
       (setq file (car e))
diff --git a/lisp/emacs-lisp/cl-indent.el b/lisp/emacs-lisp/cl-indent.el
index c88e15d5a8b..9d8aae28441 100644
--- a/lisp/emacs-lisp/cl-indent.el
+++ b/lisp/emacs-lisp/cl-indent.el
@@ -162,9 +162,9 @@ is set to `defun'.")
     (error t)))
 
 (defun lisp-indent-find-method (symbol &optional no-compat)
-  "Find the lisp indentation function for SYMBOL.
+  "Find the Lisp indentation function for SYMBOL.
 If NO-COMPAT is non-nil, do not retrieve indenters intended for
-the standard lisp indent package."
+the standard Lisp indent package."
   (or (and (derived-mode-p 'emacs-lisp-mode)
            (get symbol 'common-lisp-indent-function-for-elisp))
       (get symbol 'common-lisp-indent-function)
diff --git a/lisp/emacs-lisp/copyright.el b/lisp/emacs-lisp/copyright.el
index d2e4891acee..9da370a725d 100644
--- a/lisp/emacs-lisp/copyright.el
+++ b/lisp/emacs-lisp/copyright.el
@@ -120,7 +120,7 @@ When this is `function', only ask when called non-interactively."
     (re-search-forward regexp bound noerror count)))
 
 (defun copyright-start-point ()
-  "Return point-min or point-max, depending on `copyright-at-end-flag'."
+  "Return `point-min' or `point-max', depending on `copyright-at-end-flag'."
   (if copyright-at-end-flag
       (point-max)
     (point-min)))
@@ -135,7 +135,7 @@ When this is `function', only ask when called non-interactively."
 (defun copyright-find-copyright ()
   "Return non-nil if a copyright header suitable for updating is found.
 The header must match `copyright-regexp' and `copyright-names-regexp', if set.
-This function sets the match-data that `copyright-update-year' uses."
+This function sets the match data that `copyright-update-year' uses."
   (widen)
   (goto-char (copyright-start-point))
   ;; In case the regexp is rejected.  This is useful because
diff --git a/lisp/emacs-lisp/debug.el b/lisp/emacs-lisp/debug.el
index f76ae3fe69f..8da9fb76821 100644
--- a/lisp/emacs-lisp/debug.el
+++ b/lisp/emacs-lisp/debug.el
@@ -390,7 +390,7 @@ Include the reason for debugger entry from ARGS."
         (`(set ,buffer) (format "setting %s in buffer %s to %s"
                                 symbol buffer
                                 (backtrace-print-to-string newval)))
-        (_ (error "unrecognized watchpoint triggered %S" (cdr args))))
+        (_ (error "Unrecognized watchpoint triggered %S" (cdr args))))
       ": ")
      (insert ?\n))
     ;; Debugger entered for an error.
diff --git a/lisp/emacs-lisp/disass.el b/lisp/emacs-lisp/disass.el
index 712fa511707..6c019e7387c 100644
--- a/lisp/emacs-lisp/disass.el
+++ b/lisp/emacs-lisp/disass.el
@@ -114,7 +114,7 @@ redefine OBJECT if it is a symbol."
     (if (eq (car-safe obj) 'byte-code)
 	(setq obj `(lambda () ,obj)))
     (when (consp obj)
-      (unless (functionp obj) (error "not a function"))
+      (unless (functionp obj) (error "Not a function"))
       (if (assq 'byte-code obj)
           nil
         (if interactive-p (message (if name
@@ -183,7 +183,7 @@ redefine OBJECT if it is a symbol."
 
 
 (defun disassemble-1 (obj indent)
-  "Prints the byte-code call OBJ in the current buffer.
+  "Print the byte-code call OBJ in the current buffer.
 OBJ should be a call to BYTE-CODE generated by the byte compiler."
   (let (bytes constvec)
     (if (consp obj)
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index d9b5ea74f6e..dfbae746cc1 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -32,7 +32,7 @@
 ;; natural for the minor-mode end-users.
 
 ;; For each mode, easy-mmode defines the following:
-;; <mode>      : The minor mode predicate. A buffer-local variable.
+;; <mode>      : The minor mode predicate.  A buffer-local variable.
 ;; <mode>-map  : The keymap possibly associated to <mode>.
 ;;       see `define-minor-mode' documentation
 ;;
@@ -182,7 +182,7 @@ BODY contains code to execute each time the mode is enabled or disabled.
                 be assigned to PLACE.  If you specify a :variable, this function
                 does not define a MODE variable (nor any of the terms used
 		in :variable).
-:after-hook     A single lisp form which is evaluated after the mode hooks
+:after-hook     A single Lisp form which is evaluated after the mode hooks
                 have been run.  It should not be quoted.
 
 For example, you could write
diff --git a/lisp/emacs-lisp/eieio-custom.el b/lisp/emacs-lisp/eieio-custom.el
index d7d078b2d94..4813ce8c33f 100644
--- a/lisp/emacs-lisp/eieio-custom.el
+++ b/lisp/emacs-lisp/eieio-custom.el
@@ -333,7 +333,7 @@ Optional argument GROUP is the sub-group of slots to display."
   (let ((map (make-sparse-keymap)))
     (set-keymap-parent map widget-keymap)
     map)
-  "Keymap for EIEIO Custom mode")
+  "Keymap for EIEIO Custom mode.")
 
 (define-derived-mode eieio-custom-mode fundamental-mode "EIEIO Custom"
   "Major mode for customizing EIEIO objects.
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index cec89cf3bc5..21f262adc6e 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -437,7 +437,7 @@ return any documentation.")
 (defvar eldoc-display-functions
   '(eldoc-display-in-echo-area eldoc-display-in-buffer)
   "Hook of functions tasked with displaying ElDoc results.
-Each function is passed two arguments: DOCS and INTERACTIVE. DOCS
+Each function is passed two arguments: DOCS and INTERACTIVE.  DOCS
 is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2
 VALUE2 ...).  STRING is a string containing the documentation's
 text and the remainder of DOC is an optional list of
diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el
index c2b026dc822..8c33b7c9948 100644
--- a/lisp/emacs-lisp/elp.el
+++ b/lisp/emacs-lisp/elp.el
@@ -407,11 +407,11 @@ original definition, use \\[elp-restore-function] or \\[elp-restore-all]."
   (>= (aref vec1 0) (aref vec2 0)))
 
 (defun elp-sort-by-total-time (vec1 vec2)
-  "Predicate to sort by highest total time spent in function. See `sort'."
+  "Predicate to sort by highest total time spent in function.  See `sort'."
   (>= (aref vec1 1) (aref vec2 1)))
 
 (defun elp-sort-by-average-time (vec1 vec2)
-  "Predicate to sort by highest average time spent in function. See `sort'."
+  "Predicate to sort by highest average time spent in function.  See `sort'."
   (>= (aref vec1 2) (aref vec2 2)))
 
 (defsubst elp-pack-number (number width)
diff --git a/lisp/emacs-lisp/ewoc.el b/lisp/emacs-lisp/ewoc.el
index d3ace97945f..ca29b6d8c9b 100644
--- a/lisp/emacs-lisp/ewoc.el
+++ b/lisp/emacs-lisp/ewoc.el
@@ -55,7 +55,7 @@
 ;;
 ;; Ewoc can be considered as the `view' part of a model-view-controller.
 ;;
-;; A `element' can be any lisp object.  When you use the ewoc
+;; An `element' can be any Lisp object.  When you use the ewoc
 ;; package you specify a pretty-printer, a function that inserts
 ;; a printable representation of the element in the buffer.  (The
 ;; pretty-printer should use "insert" and not
@@ -67,7 +67,7 @@
 ;; fixed when the ewoc is created).  The header and the footer
 ;; are constant strings.  They appear before and after the elements.
 ;;
-;; Ewoc does not affect the mode of the buffer in any way. It
+;; Ewoc does not affect the mode of the buffer in any way.  It
 ;; merely makes it easy to connect an underlying data representation
 ;; to the buffer contents.
 ;;
@@ -117,7 +117,7 @@
     (unless (eq dll L) L)))
 
 (defun ewoc--node-nth (dll n)
-  "Return the Nth node from the doubly linked list `dll'.
+  "Return the Nth node from the doubly linked list DLL.
 N counts from zero.  If N is negative, return the -(N+1)th last element.
 If N is out of range, return nil.
 Thus, (ewoc--node-nth dll 0) returns the first node,
diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index 7bc3e6b25ff..4bbcf453569 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -765,7 +765,7 @@ See `find-function-on-key'."
 
 ;;;###autoload
 (defun find-function-setup-keys ()
-  "Define some key bindings for the find-function family of functions."
+  "Define some key bindings for the `find-function' family of functions."
   (define-key ctl-x-map "F" 'find-function)
   (define-key ctl-x-4-map "F" 'find-function-other-window)
   (define-key ctl-x-5-map "F" 'find-function-other-frame)
diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el
index 4ae20ba4205..2acf939bed7 100644
--- a/lisp/emacs-lisp/generator.el
+++ b/lisp/emacs-lisp/generator.el
@@ -467,7 +467,7 @@ DYNAMIC-VAR bound to STATIC-VAR."
           (guard (cps--special-form-p name))
           (guard (not (memq name cps-standard-special-forms))))
      name                               ; Shut up byte compiler
-     (error "special form %S incorrect or not supported" form))
+     (error "Special form %S incorrect or not supported" form))
 
     ;; Process regular function applications with nontrivial
     ;; parameters, converting them to applications of trivial
@@ -633,7 +633,7 @@ modified copy."
                          ;; If we're exiting non-locally (error, quit,
                          ;; etc.)  close the iterator.
                          ,(cps--make-close-iterator-form terminal-state)))))
-                  (t (error "unknown iterator operation %S" op))))))
+                  (t (error "Unknown iterator operation %S" op))))))
          ,(when finalizer-symbol
             '(funcall iterator
                       :stash-finalizer
@@ -711,7 +711,7 @@ iterator cannot supply more values."
 
 (defun iter-close (iterator)
   "Terminate an iterator early.
-Run any unwind-protect handlers in scope at the point ITERATOR
+Run any `unwind-protect' handlers in scope at the point ITERATOR
 is blocked."
   (funcall iterator :close nil))
 
diff --git a/lisp/emacs-lisp/let-alist.el b/lisp/emacs-lisp/let-alist.el
index 433b37d7923..2d634b7b037 100644
--- a/lisp/emacs-lisp/let-alist.el
+++ b/lisp/emacs-lisp/let-alist.el
@@ -57,7 +57,7 @@
 ;;       .site.contents))
 ;;
 ;; If you nest `let-alist' invocations, the inner one can't access
-;; the variables of the outer one. You can, however, access alists
+;; the variables of the outer one.  You can, however, access alists
 ;; inside the original alist by using dots inside the symbol, as
 ;; displayed in the example above by the `.site.contents'.
 ;;
@@ -137,7 +137,7 @@ essentially expands to
       .site.contents))
 
 If you nest `let-alist' invocations, the inner one can't access
-the variables of the outer one. You can, however, access alists
+the variables of the outer one.  You can, however, access alists
 inside the original alist by using dots inside the symbol, as
 displayed in the example above."
   (declare (indent 1) (debug t))
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 9bbc7f8bba2..42e943a60df 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -824,7 +824,7 @@ function is `common-lisp-indent-function'."
   "Return Parse-Partial-Sexp State at POS, defaulting to point.
 Like `syntax-ppss' but includes the character address of the last
 complete sexp in the innermost containing list at position
-2 (counting from 0).  This is important for lisp indentation."
+2 (counting from 0).  This is important for Lisp indentation."
   (unless pos (setq pos (point)))
   (let ((pss (syntax-ppss pos)))
     (if (nth 9 pss)
diff --git a/lisp/emacs-lisp/macroexp.el b/lisp/emacs-lisp/macroexp.el
index 61c1ea490f0..1e4fdd126cb 100644
--- a/lisp/emacs-lisp/macroexp.el
+++ b/lisp/emacs-lisp/macroexp.el
@@ -243,19 +243,19 @@ is executed without being compiled first."
     (while arglist
       (cond ((eq (car arglist) '&optional)
              ;; ok, I'll let this slide because funcall_lambda() does...
-             ;; (if optionalp (error "multiple &optional keywords in %s" name))
+             ;; (if optionalp (error "Multiple &optional keywords in %s" name))
              (if restp (error "&optional found after &rest in %s" name))
              (if (null (cdr arglist))
-                 (error "nothing after &optional in %s" name))
+                 (error "Nothing after &optional in %s" name))
              (setq optionalp t))
             ((eq (car arglist) '&rest)
              ;; ...but it is by no stretch of the imagination a reasonable
              ;; thing that funcall_lambda() allows (&rest x y) and
              ;; (&rest x &optional y) in arglists.
              (if (null (cdr arglist))
-                 (error "nothing after &rest in %s" name))
+                 (error "Nothing after &rest in %s" name))
              (if (cdr (cdr arglist))
-                 (error "multiple vars after &rest in %s" name))
+                 (error "Multiple vars after &rest in %s" name))
              (setq restp t))
             (restp
              (setq bindings (cons (list (car arglist)
diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el
index 41a9c7242b3..a2a5aaed046 100644
--- a/lisp/emacs-lisp/nadvice.el
+++ b/lisp/emacs-lisp/nadvice.el
@@ -245,7 +245,7 @@ WHERE is a symbol to select an entry in `advice--where-alist'."
                           (list (advice--remove-function rest function)))))))
 
 (defvar advice--buffer-local-function-sample nil
-  "keeps an example of the special \"run the default value\" functions.
+  "Keeps an example of the special \"run the default value\" functions.
 These functions play the same role as t in buffer-local hooks, and to recognize
 them, we keep a sample here against which to compare.  Each instance is
 different, but `function-equal' will hopefully ignore those differences.")
diff --git a/lisp/emacs-lisp/package-x.el b/lisp/emacs-lisp/package-x.el
index 2e327d16de4..0175857b7f5 100644
--- a/lisp/emacs-lisp/package-x.el
+++ b/lisp/emacs-lisp/package-x.el
@@ -34,7 +34,7 @@
 ;; (possibly one on a remote machine, accessed via Tramp).
 
 ;; Then call M-x package-upload-file, which prompts for a file to
-;; upload. Alternatively, M-x package-upload-buffer uploads the
+;; upload.  Alternatively, M-x package-upload-buffer uploads the
 ;; current buffer, if it's visiting a package file.
 
 ;; Once a package is uploaded, users can access it via the Package
diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 63b187be02b..c6173c710f7 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -86,7 +86,7 @@
         (funcall pf (and me (symbolp me) (edebug-get-spec me))))))
 
 (defun pcase--get-macroexpander (s)
-  "Return the macroexpander for pcase pattern head S, or nil"
+  "Return the macroexpander for pcase pattern head S, or nil."
   (get s 'pcase-macroexpander))
 
 ;;;###autoload
diff --git a/lisp/emacs-lisp/shadow.el b/lisp/emacs-lisp/shadow.el
index 02f2ad3d816..e2a24e9949c 100644
--- a/lisp/emacs-lisp/shadow.el
+++ b/lisp/emacs-lisp/shadow.el
@@ -31,13 +31,13 @@
 ;; a file with the same name in a later load-path directory.  When
 ;; this is unintentional, it may result in problems that could have
 ;; been easily avoided.  This occurs often (to me) when installing a
-;; new version of emacs and something in the site-lisp directory
-;; has been updated and added to the emacs distribution.  The old
-;; version, now outdated, shadows the new one. This is obviously
+;; new version of Emacs and something in the site-lisp directory
+;; has been updated and added to the Emacs distribution.  The old
+;; version, now outdated, shadows the new one.  This is obviously
 ;; undesirable.
 ;;
 ;; The `list-load-path-shadows' function was run when you installed
-;; this version of emacs. To run it by hand in emacs:
+;; this version of Emacs.  To run it by hand in emacs:
 ;;
 ;;     M-x list-load-path-shadows
 ;;
@@ -181,7 +181,7 @@ See the documentation for `list-load-path-shadows' for further information."
   "Keywords to highlight in `load-path-shadows-mode'.")
 
 (define-derived-mode load-path-shadows-mode fundamental-mode "LP-Shadows"
-  "Major mode for load-path shadows buffer."
+  "Major mode for `load-path' shadows buffer."
   (setq-local font-lock-defaults
               '((load-path-shadows-font-lock-keywords)))
   (setq buffer-undo-list t
diff --git a/lisp/emacs-lisp/testcover.el b/lisp/emacs-lisp/testcover.el
index e75f15140aa..f5a624bb61b 100644
--- a/lisp/emacs-lisp/testcover.el
+++ b/lisp/emacs-lisp/testcover.el
@@ -20,7 +20,6 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 
-
 ;;; Commentary:
 
 ;; * Use `testcover-start' to instrument a Lisp file for coverage testing.
@@ -62,6 +61,8 @@
 ;;   error if these "potentially" 1-valued forms actually return differing
 ;;   values.
 
+;;; Code:
+
 (eval-when-compile (require 'cl-lib))
 (require 'edebug)
 (provide 'testcover)
@@ -80,8 +81,9 @@
 (defcustom testcover-constants
   '(nil t emacs-build-time emacs-version emacs-major-version
     emacs-minor-version)
-  "Variables whose values never change.  No brown splotch is shown for
-these.  This list is quite incomplete!"
+  "Variables whose values never change.
+No brown splotch is shown for these.  This list is quite
+incomplete!"
   :group 'testcover
   :type '(repeat variable))
 
@@ -103,8 +105,8 @@ incomplete!  Notes: Nobody ever changes the current global map."
 
 (defcustom testcover-noreturn-functions
   '(error noreturn throw signal)
-  "Subset of `testcover-1value-functions' -- these never return.  We mark
-them as having returned nil just before calling them."
+  "Subset of `testcover-1value-functions' -- these never return.
+We mark them as having returned nil just before calling them."
   :group 'testcover
   :type '(repeat symbol))
 
@@ -126,25 +128,26 @@ side-effect-free functions should be here."
     set set-default set-marker-insertion-type setq setq-default
     with-current-buffer with-output-to-temp-buffer with-syntax-table
     with-temp-buffer with-temp-file with-temp-message with-timeout)
-  "Functions whose return value is the same as their last argument.  No
-brown splotch is shown for these if the last argument is a constant or a
-call to one of the `testcover-1value-functions'.  This list is probably
-incomplete!"
+  "Functions whose return value is the same as their last argument.
+No brown splotch is shown for these if the last argument is a
+constant or a call to one of the `testcover-1value-functions'.
+This list is probably incomplete!"
   :group 'testcover
   :type '(repeat symbol))
 
 (defcustom testcover-prog1-functions
   '(prog1 unwind-protect)
-  "Functions whose return value is the same as their first argument.  No
-brown splotch is shown for these if the first argument is a constant or a
-call to one of the `testcover-1value-functions'."
+  "Functions whose return value is the same as their first argument.
+No brown splotch is shown for these if the first argument is a
+constant or a call to one of the `testcover-1value-functions'."
   :group 'testcover
   :type '(repeat symbol))
 
 (defcustom testcover-potentially-1value-functions
   '(add-hook and beep or remove-hook unless when)
-  "Functions that are potentially 1-valued.  No brown splotch if actually
-1-valued, no error if actually multi-valued."
+  "Functions that are potentially 1-valued.
+No brown splotch if actually 1-valued, no error if actually
+multi-valued."
   :group 'testcover
   :type '(repeat symbol))
 
@@ -164,8 +167,7 @@ call to one of the `testcover-1value-functions'."
 ;;;=========================================================================
 
 (defvar testcover-module-constants nil
-  "Symbols declared with defconst in the last file processed by
-`testcover-start'.")
+  "Symbols declared with defconst in the last file processed by `testcover-start'.")
 
 (defvar testcover-module-1value-functions nil
   "Symbols declared with defun in the last file processed by
@@ -388,7 +390,7 @@ coverage tests.  This function creates many overlays."
     (error nil)))  ;Ignore "No such buffer" errors
 
 (defun testcover-next-mark ()
-  "Moves point to next line in current buffer that has a splotch."
+  "Move point to next line in current buffer that has a splotch."
   (interactive)
   (goto-char (next-overlay-change (point)))
   (end-of-line))
diff --git a/lisp/emacs-lisp/thunk.el b/lisp/emacs-lisp/thunk.el
index 7e349d22a49..6f2e42af50b 100644
--- a/lisp/emacs-lisp/thunk.el
+++ b/lisp/emacs-lisp/thunk.el
@@ -30,7 +30,7 @@
 ;; forms.
 ;;
 ;; Use `thunk-delay' to delay the evaluation of a form (requires
-;; lexical-binding), and `thunk-force' to evaluate it. The result of
+;; lexical-binding), and `thunk-force' to evaluate it.  The result of
 ;; the evaluation is cached, and only happens once.
 ;;
 ;; Here is an example of a form which evaluation is delayed: