Subject: bug#44858: [PATCH] Make byte-compiler warn about wide docstrings

From: Stefan Kangas <[email-masked]>
Date: Thu, 10 Dec 2020 14:59:16 -0600

Lars Ingebrigtsen <[email-masked]> writes:

> Stefan Kangas <[email-masked]> writes:
>
>> The problem I saw was basically warnings
>> about symbols only visible after macro expansion, and that warnings
>> would point to entirely the wrong line and column.
>
> Oh, OK, the problem was in the lines/column output, not with detecting
> the doc strings themselves?
>
> Yes, that sounds like a problem, but...  I think we can live with
> inaccurate lines here.

OK.  The next issue is actually fixing all those docstrings though...

>>> Yes, the autogenerated docstrings should be fixed, too -- mostly by
>>> running them through `fill-paragraph'.
>>
>> I tried that in e.g. define-derived-mode, but fill.el is loaded after
>> derived.el.  So it seems like there is some fun to be had in figuring
>> out the dependencies there...
>
> Yeah, I guess fill.el is a pretty far down in the list of things that
> loadup.el loads?
>
> However, we could make a super-simple function for filling doc
> strings -- doing something that's good enough for that particular task
> shouldn't take more than a few lines.

True.  Please find attached three patches:

1. The original patch adjusted with the heuristic proposed by Eli.

2. Avoid wide docstrings in define-minor-mode.

3. Fixing most wide docstring warnings.

With these three patches applied, around 22 wide docstring warnings
remain in our tree for defvar's.  I found it hard to fix them as I'm not
very familiar with the code in question, and I couldn't just simplify
the wording from the context.

I'm assuming we don't want to push this without fixing those warnings,
so I would really appreciate some help with the remaining couple of
warnings.

Should we perhaps try to get this applied before starting work on
defuns?  Or should I just push a branch for this work?
From b6e47cf7f9f2618a8509d7178125ce909914a75b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
Date: Sun, 6 Dec 2020 12:44:19 +0100
Subject: [PATCH 1/3] Make byte-compiler warn about wide docstrings

* lisp/emacs-lisp/bytecomp.el (byte-compile--wide-docstring-p):
(byte-compile-docstring-length-warn): New defuns.
(byte-compile-docstring-max-column): New defcustom.
(byte-compile--wide-docstring-substitution-len): New variable.
(byte-compile-warning-types, byte-compile-warnings): New value
'docstrings'.
(byte-compile-file-form-autoload, byte-compile-file-form-defvar):
(byte-compile-file-form-defvar-function, byte-compile-lambda):
(byte-compile-defvar, byte-compile-file-form-defalias): Warn about too
wide docstrings.

* test/lisp/emacs-lisp/bytecomp-tests.el
(bytecomp-warn-wide-docstring/defconst)
(bytecomp-warn-wide-docstring/defvar): New tests.
(bytecomp--define-warning-file-test): New macro.
(bytecomp/warn-long-docstring-autoload\.el)
(bytecomp/warn-long-docstring-custom-declare-variable\.el)
(bytecomp/warn-long-docstring-defalias\.el)
(bytecomp/warn-long-docstring-defconst\.el)
(bytecomp/warn-long-docstring-define-abbrev-table\.el)
(bytecomp/warn-long-docstring-define-obsolete-function-alias\.el)
(bytecomp/warn-long-docstring-define-obsolete-variable-alias\.el)
(bytecomp/warn-long-docstring-defun\.el)
(bytecomp/warn-long-docstring-defvar\.el)
(bytecomp/warn-long-docstring-defvaralias\.el)
(bytecomp/warn-long-docstring-ignore-fill-column\.el)
(bytecomp/warn-long-docstring-ignore\.el): New tests.
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-autoload.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-custom-declare-variable.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defalias.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defconst.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-abbrev-table.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-function-alias.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-variable-alias.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defun.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvar.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvaralias.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore-fill-column.el:
* test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore.el:
New files.
---
 etc/NEWS                                      |  9 ++-
 etc/TODO                                      |  2 -
 lisp/emacs-lisp/bytecomp.el                   | 76 ++++++++++++++++++-
 .../warn-long-docstring-autoload.el           |  3 +
 ...-long-docstring-custom-declare-variable.el |  4 +
 .../warn-long-docstring-defalias.el           |  3 +
 .../warn-long-docstring-defconst.el           |  3 +
 ...warn-long-docstring-define-abbrev-table.el |  3 +
 ...ocstring-define-obsolete-function-alias.el |  3 +
 ...ocstring-define-obsolete-variable-alias.el |  3 +
 .../warn-long-docstring-defun.el              |  3 +
 .../warn-long-docstring-defvar.el             |  3 +
 .../warn-long-docstring-defvaralias.el        |  3 +
 .../warn-long-docstring-ignore-fill-column.el |  7 ++
 .../warn-long-docstring-ignore.el             |  7 ++
 test/lisp/emacs-lisp/bytecomp-tests.el        | 59 ++++++++++++++
 16 files changed, 186 insertions(+), 5 deletions(-)
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-autoload.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-custom-declare-variable.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defalias.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defconst.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-abbrev-table.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-function-alias.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-variable-alias.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defun.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvar.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvaralias.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore-fill-column.el
 create mode 100644 test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore.el

diff --git a/etc/NEWS b/etc/NEWS
index 83fe7a349e..4dbd15ee5b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2059,8 +2059,10 @@ menu handling.
 +++
 ** 'inhibit-nul-byte-detection' is renamed to 'inhibit-null-byte-detection'.
 
+** byte compiler
+
 +++
-** New byte-compiler check for missing dynamic variable declarations.
+*** New byte-compiler check for missing dynamic variable declarations.
 It is meant as an (experimental) aid for converting Emacs Lisp code
 to lexical binding, where dynamic (special) variables bound in one
 file can affect code in another.  For details, see the manual section
@@ -2070,6 +2072,11 @@ file can affect code in another.  For details, see the manual section
 ** 'byte-recompile-directory' can now compile symlinked ".el" files.
 This is achieved by giving a non-nil FOLLOW-SYMLINKS parameter.
 
+*** The byte-compiler now warns about too wide documentation strings.
+By default, it will warn if a documentation string is wider than the
+largest of 80 characters or 'fill-column'.  See the new user
+option 'byte-compile-docstring-max-column'.
+
 ---
 ** 'unload-feature' now also tries to undo additions to buffer-local hooks.
 
diff --git a/etc/TODO b/etc/TODO
index 8e93e7fb10..38dfda424f 100644
--- a/etc/TODO
+++ b/etc/TODO
@@ -572,8 +572,6 @@ Do this for some or all errors associated with using subprocesses.
 ** Maybe reinterpret 'parse-error' as a category of errors
 Put some other errors under it.
 
-** Make byte-compiler warn when a doc string is too wide
-
 ** Make byte-optimization warnings issue accurate line numbers
 
 ** Record the sxhash of the default value for customized variables
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 0acd527697..c5f2c757dd 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -297,7 +297,8 @@ byte-compile-error-on-warn
 (defconst byte-compile-warning-types
   '(redefine callargs free-vars unresolved
              obsolete noruntime interactive-only
-	     make-local mapcar constants suspicious lexical lexical-dynamic)
+             make-local mapcar constants suspicious lexical lexical-dynamic
+             docstrings)
   "The list of warning types used when `byte-compile-warnings' is t.")
 (defcustom byte-compile-warnings t
   "List of warnings that the byte-compiler should issue (t for all).
@@ -320,6 +321,8 @@ byte-compile-warnings
   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 80 characters,
+              or `fill-column', whichever is bigger)
   suspicious  constructs that usually don't do what the coder wanted.
 
 If the list begins with `not', then the remaining elements specify warnings to
@@ -1557,6 +1560,69 @@ byte-compile-arglist-warn
            (if (equal sig1 '(1 . 1)) "argument" "arguments")
            (byte-compile-arglist-signature-string sig2)))))))
 
+(defvar byte-compile--wide-docstring-substitution-len 3
+  "Substitution width used in `byte-compile--wide-docstring-p'.")
+
+(defun byte-compile--wide-docstring-p (docstring col)
+  "Return t if string DOCSTRING is wider than COL.
+Ignore any `substitute-command-keys' substitutions."
+  (string-match
+   (format "^.\\{%s,\\}$" (int-to-string (1+ col)))
+   ;; Ignore these `substitute-command-keys' substitutions.
+   (replace-regexp-in-string
+    (rx "\\" (or "="
+                 (seq "<" (* (not ">")) ">")
+                 (seq "{" (* (not "}")) "}")))
+    ""
+    ;; Assume that these are of a given length.
+    (replace-regexp-in-string
+     (rx "\\" (or (seq "[" (* (not "]")) "]")))
+     (make-string byte-compile--wide-docstring-substitution-len ?x)
+     docstring))))
+
+(defcustom byte-compile-docstring-max-column 80
+  "Length that a doc string can be before the byte-compiler reports a warning."
+  :group 'bytecomp
+  :type 'integer
+  :safe #'integerp
+  :version "28.1")
+
+(defun byte-compile-docstring-length-warn (form)
+  "Warn if documentation string of FORM is too wide.
+It is too wide if it is longer than the largest of `fill-column'
+and `byte-compile-docstring-max-column'."
+  ;; This has some limitations that it would be nice to fix:
+  ;; 1. We don't try to handle defuns.  It is somewhat tricky to get
+  ;;    it right since `defun' is a macro.  Also, some macros
+  ;;    themselves produce defuns (e.g. `define-derived-mode').
+  ;; 2. We assume that any `subsititute-command-keys' command replacement has a
+  ;;    given length.  We can't reliably do these replacements, since the value
+  ;;    of the keymaps in general can't be known at compile time.
+  (when (byte-compile-warning-enabled-p 'docstrings)
+    (let ((col (max byte-compile-docstring-max-column fill-column))
+          kind name docs)
+      (pcase (car form)
+        ((or 'autoload 'custom-declare-variable 'defalias
+             'defconst 'define-abbrev-table
+             'defvar 'defvaralias)
+         (setq kind (nth 0 form))
+         (setq name (nth 1 form))
+         (setq docs (nth 3 form)))
+        ;; Here is how one could add lambda's here:
+        ;; ('lambda
+        ;;   (setq kind "")   ; can't be "function", unfortunately
+        ;;   (setq docs (and (stringp (nth 2 form))
+        ;;                   (nth 2 form))))
+        )
+      (when (and (consp name) (eq (car name) 'quote))
+        (setq name (cadr name)))
+      (setq name (if name (format " `%s'" name) ""))
+      (when (and kind docs (stringp docs)
+                 (byte-compile--wide-docstring-p docs col))
+        (byte-compile-warn "%s%s docstring wider than %s characters"
+                           kind name col))))
+  form)
+
 (defun byte-compile-print-syms (str1 strn syms)
   (when syms
     (byte-compile-set-symbol-position (car syms) t))
@@ -2387,7 +2453,8 @@ byte-compile-file-form-autoload
              (delq (assq funsym byte-compile-unresolved-functions)
                    byte-compile-unresolved-functions)))))
   (if (stringp (nth 3 form))
-      form
+      (prog1 form
+        (byte-compile-docstring-length-warn form))
     ;; No doc string, so we can compile this as a normal form.
     (byte-compile-keep-pending form 'byte-compile-normal-call)))
 
@@ -2415,6 +2482,7 @@ byte-compile-file-form-defvar
   (if (and (null (cddr form))		;No `value' provided.
            (eq (car form) 'defvar))     ;Just a declaration.
       nil
+    (byte-compile-docstring-length-warn form)
     (cond ((consp (nth 2 form))
            (setq form (copy-sequence form))
            (setcar (cdr (cdr form))
@@ -2438,6 +2506,7 @@ byte-compile-file-form-defvar-function
        (if (byte-compile-warning-enabled-p 'suspicious)
            (byte-compile-warn
             "Alias for `%S' should be declared before its referent" newname)))))
+  (byte-compile-docstring-length-warn form)
   (byte-compile-keep-pending form))
 
 (put 'custom-declare-variable 'byte-hunk-handler
@@ -2821,6 +2890,7 @@ byte-compile-lambda
     (unless (eq 'lambda (car-safe fun))
       (error "Not a lambda list: %S" fun))
     (byte-compile-set-symbol-position 'lambda))
+  (byte-compile-docstring-length-warn fun)
   (byte-compile-check-lambda-list (nth 1 fun))
   (let* ((arglist (nth 1 fun))
          (arglistvars (byte-compile-arglist-vars arglist))
@@ -4601,6 +4671,7 @@ byte-compile-defvar
              (byte-compile-warning-enabled-p 'lexical (nth 1 form)))
     (byte-compile-warn "global/dynamic var `%s' lacks a prefix"
                        (nth 1 form)))
+  (byte-compile-docstring-length-warn form)
   (let ((fun (nth 0 form))
 	(var (nth 1 form))
 	(value (nth 2 form))
@@ -4675,6 +4746,7 @@ byte-compile-file-form-defalias
       ;; - `arg' is the expression to which it is defined.
       ;; - `rest' is the rest of the arguments.
       (`(,_ ',name ,arg . ,rest)
+       (byte-compile-docstring-length-warn form)
        (pcase-let*
            ;; `macro' is non-nil if it defines a macro.
            ;; `fun' is the function part of `arg' (defaults to `arg').
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-autoload.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-autoload.el
new file mode 100644
index 0000000000..96deb1bbb0
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-autoload.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(autoload 'foox "foo"
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-custom-declare-variable.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-custom-declare-variable.el
new file mode 100644
index 0000000000..2a4700bfda
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-custom-declare-variable.el
@@ -0,0 +1,4 @@
+;;; -*- lexical-binding: t -*-
+(custom-declare-variable
+ 'foo t
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defalias.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defalias.el
new file mode 100644
index 0000000000..a4235d22bd
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defalias.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(defalias 'foo #'ignore
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defconst.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defconst.el
new file mode 100644
index 0000000000..946f01989a
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defconst.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(defconst foo-bar nil
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-abbrev-table.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-abbrev-table.el
new file mode 100644
index 0000000000..3da9ccd48c
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-abbrev-table.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(define-abbrev-table 'foo ()
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-function-alias.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-function-alias.el
new file mode 100644
index 0000000000..fea841b12e
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-function-alias.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(define-obsolete-function-alias 'foo #'ignore "99.1"
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-variable-alias.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-variable-alias.el
new file mode 100644
index 0000000000..2d5f201cb6
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-define-obsolete-variable-alias.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(define-obsolete-variable-alias 'foo 'ignore "99.1"
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defun.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defun.el
new file mode 100644
index 0000000000..94b0e80c97
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defun.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(defun foo ()
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvar.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvar.el
new file mode 100644
index 0000000000..4bf8c17c3f
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvar.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(defvar foo-bar nil
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvaralias.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvaralias.el
new file mode 100644
index 0000000000..52fdc17f5b
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-defvaralias.el
@@ -0,0 +1,3 @@
+;;; -*- lexical-binding: t -*-
+(defvaralias 'foo-bar #'ignore
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore-fill-column.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore-fill-column.el
new file mode 100644
index 0000000000..1ff554f370
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore-fill-column.el
@@ -0,0 +1,7 @@
+;;; -*- lexical-binding: t -*-
+(defvar foo-bar nil
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
+
+;; Local Variables:
+;; fill-column: 100
+;; End:
diff --git a/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore.el b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore.el
new file mode 100644
index 0000000000..c80ddd180d
--- /dev/null
+++ b/test/lisp/emacs-lisp/bytecomp-resources/warn-long-docstring-ignore.el
@@ -0,0 +1,7 @@
+;;; -*- lexical-binding: t -*-
+(defvar foo-bar nil
+  "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
+
+;; Local Variables:
+;; byte-compile-docstring-max-column: 100
+;; End:
diff --git a/test/lisp/emacs-lisp/bytecomp-tests.el b/test/lisp/emacs-lisp/bytecomp-tests.el
index 8fa4d278f1..caa9ab8f96 100644
--- a/test/lisp/emacs-lisp/bytecomp-tests.el
+++ b/test/lisp/emacs-lisp/bytecomp-tests.el
@@ -540,6 +540,16 @@ bytecomp-warn-variable-lacks-prefix
   (bytecomp--with-warning-test "foo.*lacks a prefix"
     '(defvar foo nil)))
 
+(defvar bytecomp-tests--docstring (make-string 100 ?x))
+
+(ert-deftest bytecomp-warn-wide-docstring/defconst ()
+  (bytecomp--with-warning-test "defconst.*foo.*wider than.*characters"
+    `(defconst foo t ,bytecomp-tests--docstring)))
+
+(ert-deftest bytecomp-warn-wide-docstring/defvar ()
+  (bytecomp--with-warning-test "defvar.*foo.*wider than.*characters"
+    `(defvar foo t ,bytecomp-tests--docstring)))
+
 (defmacro bytecomp--define-warning-file-test (file re-warning &optional reverse)
   `(ert-deftest ,(intern (format "bytecomp/%s" file)) ()
      :expected-result ,(if reverse :failed :passed)
@@ -639,6 +649,55 @@ "warn-variable-set-constant.el"
 (bytecomp--define-warning-file-test "warn-variable-set-nonvariable.el"
                             "variable reference to nonvariable")
 
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-autoload.el"
+ "autoload.*foox.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-custom-declare-variable.el"
+ "custom-declare-variable.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-defalias.el"
+ "defalias.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-defconst.el"
+ "defconst.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-define-abbrev-table.el"
+ "define-abbrev.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-define-obsolete-function-alias.el"
+ "defalias.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-define-obsolete-variable-alias.el"
+ "defvaralias.*foo.*wider than.*characters")
+
+;; TODO: We don't yet issue warnings for defuns.
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-defun.el"
+ "wider than.*characters" 'reverse)
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-defvar.el"
+ "defvar.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-defvaralias.el"
+ "defvaralias.*foo.*wider than.*characters")
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-ignore-fill-column.el"
+ "defvar.*foo.*wider than.*characters" 'reverse)
+
+(bytecomp--define-warning-file-test
+ "warn-long-docstring-ignore.el"
+ "defvar.*foo.*wider than.*characters" 'reverse)
+
 
 ;;;; Macro expansion.
 
-- 
2.29.2

From e0a27cba79ad8e2713775c4216943138a2d70267 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
Date: Mon, 7 Dec 2020 09:49:13 +0100
Subject: [PATCH 2/3] Avoid wide doc strings in define-minor-mode

* lisp/emacs-lisp/easy-mmode.el (define-minor-mode): Avoid producing
long documentation strings.
---
 lisp/emacs-lisp/easy-mmode.el | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 261f2508af..60ea435e8a 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -115,6 +115,16 @@ easy-mmode--mode-docstring
                                   (concat filled "\\1")
                                   doc nil nil 1)))))
 
+(defun easy-mmode--fill-string (str)
+  "Fill string STR to `fill-column' to avoid generating wide docstrings."
+  (if (< (length str) fill-column)
+      str
+      (let ((fst (substring str 0 fill-column))
+            (lst (substring str fill-column)))
+        (if (string-match ".*\\( \\(.+\\)\\)$" fst)
+            (setq fst (replace-match "\n\\2" nil nil fst 1)))
+        (concat fst lst))))
+
 ;;;###autoload
 (defalias 'easy-mmode-define-minor-mode 'define-minor-mode)
 ;;;###autoload
@@ -278,8 +288,11 @@ define-minor-mode
          ((not globalp)
           `(progn
              :autoload-end
-             (defvar ,mode ,init-value ,(format "Non-nil if %s is enabled.
-Use the command `%s' to change this variable." pretty-name mode))
+             (defvar ,mode ,init-value
+               ,(concat (format "Non-nil if %s is enabled.\n" pretty-name)
+                        (easy-mmode--fill-string
+                         (format "Use the command `%s' to change this variable."
+                                 mode))))
              (make-variable-buffer-local ',mode)))
          (t
 	  (let ((base-doc-string
-- 
2.29.2

From 3e74fcc66a623d290695ada2795d1f9a0102cbd1 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <[email-masked]>
Date: Thu, 10 Dec 2020 20:12:58 +0100
Subject: [PATCH 3/3] ; Adjust some docstrings to fit 80 columns

---
 lisp/calc/calc.el                  |  9 +++++----
 lisp/cedet/ede/generic.el          |  4 ++--
 lisp/cedet/semantic/analyze.el     |  6 ++++--
 lisp/cedet/semantic/bovine/c.el    |  3 ++-
 lisp/cedet/semantic/bovine/make.el |  4 +++-
 lisp/cedet/semantic/imenu.el       |  2 +-
 lisp/cedet/semantic/util-modes.el  |  3 ++-
 lisp/emacs-lisp/advice.el          |  5 +++--
 lisp/emacs-lisp/bytecomp.el        | 16 ++++++++++------
 lisp/emacs-lisp/cl-generic.el      |  4 ++--
 lisp/emacs-lisp/elint.el           |  2 +-
 lisp/emacs-lisp/find-func.el       |  2 +-
 lisp/emacs-lisp/seq.el             |  7 ++++---
 lisp/emulation/cua-base.el         | 10 +++++-----
 lisp/emulation/viper-init.el       |  5 +++--
 lisp/emulation/viper-keym.el       |  2 +-
 lisp/erc/erc-dcc.el                |  3 ++-
 lisp/expand.el                     |  2 +-
 lisp/font-lock.el                  |  4 ++--
 lisp/gnus/gnus-art.el              |  4 +++-
 lisp/gnus/gnus-group.el            |  2 +-
 lisp/gnus/gnus-score.el            |  2 +-
 lisp/gnus/gnus-sum.el              |  9 +++++----
 lisp/gnus/gnus-uu.el               | 12 ++++++------
 lisp/gnus/gnus.el                  |  7 ++++---
 lisp/gnus/message.el               |  6 ++++--
 lisp/gnus/nnmail.el                |  5 +++--
 lisp/gnus/nnmh.el                  |  2 +-
 lisp/gnus/nntp.el                  |  4 +++-
 lisp/ido.el                        |  2 +-
 lisp/international/mule-cmds.el    |  2 +-
 lisp/language/ethio-util.el        |  6 ++++--
 lisp/mail/feedmail.el              | 18 ++++++++++--------
 lisp/mh-e/mh-e.el                  |  2 +-
 lisp/net/imap.el                   |  2 +-
 lisp/net/rcirc.el                  |  2 +-
 lisp/net/tramp-sh.el               |  3 +--
 lisp/net/tramp.el                  |  4 ++--
 lisp/nxml/nxml-mode.el             |  6 ++++--
 lisp/obsolete/landmark.el          |  3 ++-
 lisp/obsolete/tls.el               |  6 ++++--
 lisp/org/ob-R.el                   |  2 +-
 lisp/org/org-agenda.el             |  3 ++-
 lisp/org/org-attach.el             |  2 +-
 lisp/org/org-indent.el             |  6 ++----
 lisp/org/org-protocol.el           |  6 ++++--
 lisp/org/org.el                    |  3 ++-
 lisp/progmodes/cc-vars.el          |  3 ++-
 lisp/progmodes/cperl-mode.el       |  5 ++++-
 lisp/progmodes/elisp-mode.el       |  3 ++-
 lisp/progmodes/flymake-proc.el     |  6 ++++--
 lisp/progmodes/hideif.el           |  4 ++--
 lisp/progmodes/ruby-mode.el        |  2 +-
 lisp/progmodes/verilog-mode.el     |  3 ++-
 lisp/ses.el                        |  3 ++-
 lisp/simple.el                     |  3 ++-
 lisp/tab-bar.el                    |  6 ++++--
 lisp/term.el                       |  4 ++--
 lisp/textmodes/reftex-vars.el      | 10 ++++++----
 lisp/textmodes/table.el            |  8 +++++---
 lisp/vc/ediff-diff.el              |  2 +-
 lisp/vc/ediff-init.el              |  6 +++---
 lisp/vc/ediff-merg.el              |  2 +-
 lisp/vc/ediff-mult.el              |  2 +-
 lisp/vc/ediff-wind.el              |  2 +-
 lisp/vc/smerge-mode.el             |  2 +-
 lisp/vc/vc.el                      |  5 +++--
 lisp/view.el                       |  3 ++-
 68 files changed, 180 insertions(+), 128 deletions(-)

diff --git a/lisp/calc/calc.el b/lisp/calc/calc.el
index bb02281111..5805ecdb7f 100644
--- a/lisp/calc/calc.el
+++ b/lisp/calc/calc.el
@@ -266,18 +266,18 @@ calc-embedded-announce-formula-alist
     (sgml-mode    . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
     (xml-mode     . "<!-- Embed -->\n\\(<!-- .* -->\n\\)*")
     (texinfo-mode . "@c Embed\n\\(@c .*\n\\)*"))
-  "Alist of major modes with appropriate values for `calc-embedded-announce-formula'."
+  "Alist of major modes for `calc-embedded-announce-formula'."
   :type '(alist :key-type (symbol :tag "Major mode")
                 :value-type (regexp :tag "Regexp to announce formula")))
 
 (defcustom calc-embedded-open-formula
   "\\`\\|^\n\\|\\$\\$?\\|\\\\\\[\\|^\\\\begin[^{].*\n\\|^\\\\begin{.*[^x]}.*\n\\|^@.*\n\\|^\\.EQ.*\n\\|\\\\(\\|^%\n\\|^\\.\\\\\"\n"
-  "A regular expression for the opening delimiter of a formula used by calc-embedded."
+  "Regexp for opening delimiter of a formula used by `calc-embedded'."
   :type '(regexp))
 
 (defcustom calc-embedded-close-formula
   "\\'\\|\n$\\|\\$\\$?\\|\\\\]\\|^\\\\end[^{].*\n\\|^\\\\end{.*[^x]}.*\n\\|^@.*\n\\|^\\.EN.*\n\\|\\\\)\\|\n%\n\\|^\\.\\\\\"\n"
-  "A regular expression for the closing delimiter of a formula used by calc-embedded."
+  "Regexp for the closing delimiter of a formula used by calc-embedded."
   :type '(regexp))
 
 (defcustom calc-embedded-open-close-formula-alist
@@ -721,7 +721,8 @@ calc-symbolic-mode
 (defcalcmodevar calc-matrix-mode nil
   "If `matrix', variables are assumed to be matrix-valued.
 If a number, variables are assumed to be NxN matrices.
-If `sqmatrix', variables are assumed to be square matrices of an unspecified size.
+If `sqmatrix', variables are assumed to be square matrices of an
+  unspecified size.
 If `scalar', variables are assumed to be scalar-valued.
 If nil, symbolic math routines make no assumptions about variables.")
 
diff --git a/lisp/cedet/ede/generic.el b/lisp/cedet/ede/generic.el
index b9805f6fac..0f202ddfc8 100644
--- a/lisp/cedet/ede/generic.el
+++ b/lisp/cedet/ede/generic.el
@@ -258,8 +258,8 @@ ede-generic-new-autoloader
 INTERNAL-NAME is obsolete and ignored.
 EXTERNAL-NAME is a human readable name to describe the project; it
 must be unique among all autoloaded projects.
-PROJECTFILE is a file name that identifies a project of this type to EDE, such as
-a Makefile, or SConstruct file.
+PROJECTFILE is a file name that identifies a project of this type to EDE, such
+as a Makefile, or SConstruct file.
 CLASS is the EIEIO class that is used to track this project.  It should subclass
 `ede-generic-project'."
   (ede-add-project-autoload
diff --git a/lisp/cedet/semantic/analyze.el b/lisp/cedet/semantic/analyze.el
index cafdc3bee1..f2d2279c00 100644
--- a/lisp/cedet/semantic/analyze.el
+++ b/lisp/cedet/semantic/analyze.el
@@ -235,7 +235,8 @@ semantic-analyze-find-tag-sequence
 which doesn't need to be dereferenced.
 Optional argument TYPERETURN is a symbol in which the types of all found
 will be stored.  If nil, that data is thrown away.
-Optional argument THROWSYM specifies a symbol the throw on non-recoverable error.
+Optional argument THROWSYM specifies a symbol the throw on non-recoverable
+error.
 Remaining arguments FLAGS are additional flags to apply when searching.")
 
 (defun semantic-analyze-find-tag-sequence-default
@@ -246,7 +247,8 @@ semantic-analyze-find-tag-sequence-default
 SCOPE are extra tags which are in scope.
 TYPERETURN is a symbol in which to place a list of tag classes that
 are found in SEQUENCE.
-Optional argument THROWSYM specifies a symbol the throw on non-recoverable error.
+Optional argument THROWSYM specifies a symbol the throw on non-recoverable
+error.
 Remaining arguments FLAGS are additional flags to apply when searching.
 This function knows of flags:
   `mustbeclassvariable'"
diff --git a/lisp/cedet/semantic/bovine/c.el b/lisp/cedet/semantic/bovine/c.el
index 3649d1c2f1..7f0c16136c 100644
--- a/lisp/cedet/semantic/bovine/c.el
+++ b/lisp/cedet/semantic/bovine/c.el
@@ -368,7 +368,8 @@ semantic-c-convert-spp-value-to-hideif-value
 
 (defun semantic-c-evaluate-symbol-for-hideif (spp-symbol)
   "Lookup the symbol SPP-SYMBOL (a string) to something hideif can use.
-Pulls out the symbol list, and call `semantic-c-convert-spp-value-to-hideif-value'."
+Pull out the symbol list, and call
+`semantic-c-convert-spp-value-to-hideif-value'."
   (interactive "sSymbol name: ")
   (when (symbolp spp-symbol) (setq spp-symbol (symbol-name spp-symbol)))
 
diff --git a/lisp/cedet/semantic/bovine/make.el b/lisp/cedet/semantic/bovine/make.el
index 07c55b46e2..1f15669140 100644
--- a/lisp/cedet/semantic/bovine/make.el
+++ b/lisp/cedet/semantic/bovine/make.el
@@ -50,7 +50,9 @@ semantic-lex-make-backslash-no-newline
    nil)
 
 (define-lex-regex-analyzer semantic-lex-make-command
-  "A command in a Makefile consists of a line starting with TAB, and ending at the newline."
+  "Regexp for a command in a Makefile.
+It consists of a line starting with TAB, and ending at the
+newline."
   "^\\(\t\\)"
   (let ((start (match-end 0)))
     (while (progn (end-of-line)
diff --git a/lisp/cedet/semantic/imenu.el b/lisp/cedet/semantic/imenu.el
index 25f7fdb842..ebb8ac0cd8 100644
--- a/lisp/cedet/semantic/imenu.el
+++ b/lisp/cedet/semantic/imenu.el
@@ -99,7 +99,7 @@ semantic-imenu-bucketize-type-members
 
 (defcustom semantic-imenu-sort-bucket-function nil
   "Function to use when sorting tags in the buckets of functions.
-See `semantic-bucketize' and the FILTER argument for more details on this function."
+See `semantic-bucketize' and the FILTER argument for more details."
   :group 'semantic-imenu
   :type '(radio (const :tag "No Sorting" nil)
 		(const semantic-sort-tags-by-name-increasing)
diff --git a/lisp/cedet/semantic/util-modes.el b/lisp/cedet/semantic/util-modes.el
index 776c6b1894..8bfee432c3 100644
--- a/lisp/cedet/semantic/util-modes.el
+++ b/lisp/cedet/semantic/util-modes.el
@@ -837,7 +837,8 @@ semantic-highlight-func-mode-map
   "Keymap for highlight-func minor mode.")
 
 (defvar semantic-highlight-func-popup-menu nil
-  "Menu used if the user clicks on the header line used by `semantic-highlight-func-mode'.")
+  "Menu used if the user clicks on the header line.
+Used by `semantic-highlight-func-mode'.")
 
 (easy-menu-define
   semantic-highlight-func-popup-menu
diff --git a/lisp/emacs-lisp/advice.el b/lisp/emacs-lisp/advice.el
index c8a6676b66..caa436ce23 100644
--- a/lisp/emacs-lisp/advice.el
+++ b/lisp/emacs-lisp/advice.el
@@ -2405,8 +2405,9 @@ ad-map-arglists
 Excess source arguments will be neglected, missing source arguments will be
 supplied as nil.  Returns a `funcall' or `apply' form with the second element
 being `function' which has to be replaced by an actual function argument.
-Example: (ad-map-arglists \\='(a &rest args) \\='(w x y z)) will return
-         (funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))."
+Example:
+   (ad-map-arglists \\='(a &rest args) \\='(w x y z)) will return
+   (funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))."
   (let* ((parsed-source-arglist (ad-parse-arglist source-arglist))
 	 (source-reqopt-args (append (nth 0 parsed-source-arglist)
 				     (nth 1 parsed-source-arglist)))
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index c5f2c757dd..ebb18f9e5c 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -708,7 +708,8 @@ 127
 
 ;; These store their argument in the next two bytes
 (byte-defop 129  1 byte-constant2
-   "for reference to a constant with vector index >= byte-constant-limit")
+   "for reference to a constant with vector
+index >= byte-constant-limit")
 (byte-defop 130  0 byte-goto "for unconditional jump")
 (byte-defop 131 -1 byte-goto-if-nil "to pop value and jump if it's nil")
 (byte-defop 132 -1 byte-goto-if-not-nil "to pop value and jump if it's not nil")
@@ -728,11 +729,14 @@ 138
 (byte-defop 139  0 byte-save-window-excursion-OBSOLETE
   "to make a binding to record entire window configuration")
 (byte-defop 140  0 byte-save-restriction
-  "to make a binding to record the current buffer clipping restrictions")
+  "to make a binding to record the current buffer clipping
+restrictions")
 (byte-defop 141 -1 byte-catch-OBSOLETE   ; Not generated since Emacs 25.
-  "for catch.  Takes, on stack, the tag and an expression for the body")
+  "for catch.  Takes, on stack, the tag and an expression for
+the body")
 (byte-defop 142 -1 byte-unwind-protect
-  "for unwind-protect.  Takes, on stack, an expression for the unwind-action")
+  "for unwind-protect.  Takes, on stack, an expression for
+the unwind-action")
 
 ;; For condition-case.  Takes, on stack, the variable to bind,
 ;; an expression for the body, and a list of clauses.
@@ -792,8 +796,8 @@ 182
 (defconst byte-discardN-preserve-tos byte-discardN)
 
 (byte-defop 183 -2 byte-switch
- "to take a hash table and a value from the stack, and jump to the address
-the value maps to, if any.")
+ "to take a hash table and a value from the stack, and jump to
+the address the value maps to, if any.")
 
 ;; unused: 182-191
 
diff --git a/lisp/emacs-lisp/cl-generic.el b/lisp/emacs-lisp/cl-generic.el
index b37b05b9a3..9ddf9e7333 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -811,8 +811,8 @@ cl-generic-combine-methods
 GENERIC is the generic function (mostly used for its name).
 METHODS is the list of the selected methods.
 The METHODS list is sorted from most specific first to most generic last.
-The function can use `cl-generic-call-method' to create functions that call those
-methods.")
+The function can use `cl-generic-call-method' to create functions that call
+those methods.")
 
 (unless (ignore-errors (cl-generic-generalizers t))
   ;; Temporary definition to let the next defmethod succeed.
diff --git a/lisp/emacs-lisp/elint.el b/lisp/emacs-lisp/elint.el
index ef97c8279d..b143d3ff39 100644
--- a/lisp/emacs-lisp/elint.el
+++ b/lisp/emacs-lisp/elint.el
@@ -521,7 +521,7 @@ elint-top-form
   "The currently linted top form, or nil.")
 
 (defvar elint-top-form-logged nil
-  "The value t if the currently linted top form has been mentioned in the log buffer.")
+  "Non-nil t if the currently linted top form has been mentioned in the log buffer.")
 
 (defun elint-top-form (form)
   "Lint a top FORM."
diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index ee94e1fbff..074e7db295 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -103,7 +103,7 @@ find-face-regexp
 
 (defcustom find-feature-regexp
   (concat ";;; Code:")
-  "The regexp used by `xref-find-definitions' when searching for a feature definition.
+  "Regexp used by `xref-find-definitions' when searching for a feature definition.
 Note it may contain up to one `%s' at the place where `format'
 should insert the feature name."
   ;; We search for ";;; Code" rather than (feature '%s) because the
diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el
index 4656277ea1..d91a33c140 100644
--- a/lisp/emacs-lisp/seq.el
+++ b/lisp/emacs-lisp/seq.el
@@ -317,7 +317,7 @@ seq-into
 
 ;;;###autoload
 (cl-defgeneric seq-filter (pred sequence)
-  "Return a list of all the elements for which (PRED element) is non-nil in SEQUENCE."
+  "Return a list of all elements for which (PRED element) is non-nil in SEQUENCE."
   (let ((exclude (make-symbol "exclude")))
     (delq exclude (seq-map (lambda (elt)
                              (if (funcall pred elt)
@@ -411,7 +411,8 @@ seq-contains-p
       nil))
 
 (cl-defgeneric seq-set-equal-p (sequence1 sequence2 &optional testfn)
-  "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements, regardless of order.
+  "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements.
+This does not depend on the order of the elements.
 Equality is defined by TESTFN if non-nil or by `equal' if nil."
   (and (seq-every-p (lambda (item1) (seq-contains-p sequence2 item1 testfn)) sequence1)
        (seq-every-p (lambda (item2) (seq-contains-p sequence1 item2 testfn)) sequence2)))
@@ -444,7 +445,7 @@ seq-mapcat
          (seq-map function sequence)))
 
 (cl-defgeneric seq-partition (sequence n)
-  "Return a list of the elements of SEQUENCE grouped into sub-sequences of length N.
+  "Return list of elements of SEQUENCE grouped into sub-sequences of length N.
 The last sequence may contain less than N elements.  If N is a
 negative integer or 0, nil is returned."
   (unless (< n 1)
diff --git a/lisp/emulation/cua-base.el b/lisp/emulation/cua-base.el
index 926305e607..55578d0622 100644
--- a/lisp/emulation/cua-base.el
+++ b/lisp/emulation/cua-base.el
@@ -375,11 +375,11 @@ cua-check-pending-input
 
 (defcustom cua-paste-pop-rotate-temporarily nil
   "If non-nil, \\[cua-paste-pop] only rotates the kill-ring temporarily.
-This means that both \\[yank] and the first \\[yank-pop] in a sequence always insert
-the most recently killed text.  Each immediately following \\[cua-paste-pop] replaces
-the previous text with the next older element on the `kill-ring'.
-With prefix arg, \\[universal-argument] \\[yank-pop] inserts the same text as the most
-recent \\[yank-pop] (or \\[yank]) command."
+This means that both \\[yank] and the first \\[yank-pop] in a sequence always
+insert the most recently killed text.  Each immediately following \\[cua-paste-pop]
+replaces the previous text with the next older element on the `kill-ring'.
+With prefix arg, \\[universal-argument] \\[yank-pop] inserts the same text as the
+most recent \\[yank-pop] (or \\[yank]) command."
   :type 'boolean
   :group 'cua)
 
diff --git a/lisp/emulation/viper-init.el b/lisp/emulation/viper-init.el
index 6c4afe519f..c2aae9b87f 100644
--- a/lisp/emulation/viper-init.el
+++ b/lisp/emulation/viper-init.el
@@ -475,7 +475,8 @@ viper-temp-command-ring
 
 ;; Fast keyseq and ESC keyseq timeouts
 (defcustom viper-fast-keyseq-timeout 200
-  "Key sequence separated by no more than this many milliseconds is viewed as a Vi-style macro, if such a macro is defined.
+  "Max milliseconds for a key sequence to be regarded as a Vi-style macro.
+Only regard key sequence as a macro if it is defined.
 Setting this too high may slow down your typing.  Setting this value too low
 will make it hard to use Vi-style timeout macros."
   :type 'integer
@@ -705,7 +706,7 @@ viper-search-wrap-around
 
 (viper-deflocalvar viper-related-files-and-buffers-ring nil "")
 (defcustom viper-related-files-and-buffers-ring nil
-  "List of file and buffer names that are considered to be related to the current buffer.
+  "List of file and buffer names to consider related to the current buffer.
 Related buffers can be cycled through via :R and :P commands."
   :type 'boolean
   :group 'viper-misc)
diff --git a/lisp/emulation/viper-keym.el b/lisp/emulation/viper-keym.el
index d76cf71b31..6a0fc2e984 100644
--- a/lisp/emulation/viper-keym.el
+++ b/lisp/emulation/viper-keym.el
@@ -69,7 +69,7 @@ viper-no-multiple-ESC
   :group 'viper)
 
 (defcustom viper-want-ctl-h-help nil
-  "If non-nil, C-h gets bound to help-command; otherwise, C-h gets the usual Vi bindings."
+  "If non-nil, bind C-h to help-command; otherwise, C-h gets the usual Vi bindings."
   :type 'boolean
   :group 'viper)
 
diff --git a/lisp/erc/erc-dcc.el b/lisp/erc/erc-dcc.el
index 1bce986a80..6e44001259 100644
--- a/lisp/erc/erc-dcc.el
+++ b/lisp/erc/erc-dcc.el
@@ -83,7 +83,8 @@ erc-dcc-connection-types
 
 (defvar erc-dcc-list nil
   "List of DCC connections. Looks like:
-  ((:nick \"nick!user@host\" :type GET :peer proc :parent proc :size size :file file)
+  ((:nick \"nick!user@host\" :type GET :peer proc :parent proc
+    :size size :file file)
    (:nick \"nick!user@host\" :type CHAT :peer proc :parent proc)
    (:nick \"nick\" :type SEND :peer server-proc :parent parent-proc :file
    file :sent <marker> :confirmed <marker>))
diff --git a/lisp/expand.el b/lisp/expand.el
index 77e4fc2657..c4e1d22790 100644
--- a/lisp/expand.el
+++ b/lisp/expand.el
@@ -290,7 +290,7 @@ expand-add-abbrevs
 (defvar expand-list nil "Temporary variable used by the Expand package.")
 
 (defvar expand-pos nil
-  "If non-nil, stores a vector containing markers to positions defined by the last expansion.")
+  "If non-nil, store a vector with position markers defined by the last expansion.")
 (make-variable-buffer-local 'expand-pos)
 
 (defvar expand-index 0
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 0e771e8e0a..a2cf71f946 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -2280,8 +2280,8 @@ cpp-font-lock-keywords-source-directives
 ;;			 "ifndef" "import" "include" "line" "pragma" "undef" "warning")))
 ;;
 (defconst cpp-font-lock-keywords-source-depth 0
-  "An integer representing regular expression depth of `cpp-font-lock-keywords-source-directives'.
-Used in `cpp-font-lock-keywords'.")
+  "Regular expression depth of `cpp-font-lock-keywords-source-directives'.
+This should be an integer.  Used in `cpp-font-lock-keywords'.")
 
 (defconst cpp-font-lock-keywords
   (let* ((directives cpp-font-lock-keywords-source-directives)
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 5b50bcbbe1..79d4d9087f 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -289,7 +289,9 @@ gnus-article-x-face-too-ugly
 (defcustom gnus-article-banner-alist nil
   "Banner alist for stripping.
 For example,
-     ((egroups . \"^[ \\t\\n]*-------------------+\\\\( \\\\(e\\\\|Yahoo! \\\\)Groups Sponsor -+\\\\)?....\\n\\\\(.+\\n\\\\)+\"))"
+     ((egroups . (concat \"^[ \\t\\n]*-------------------+\\\\\"
+                         \"( \\\\(e\\\\|Yahoo! \\\\)Groups Sponsor -+\\\\)?\"
+                         \"....\\n\\\\(.+\\n\\\\)+\")))"
   :version "21.1"
   :type '(repeat (cons symbol regexp))
   :group 'gnus-article-washing)
diff --git a/lisp/gnus/gnus-group.el b/lisp/gnus/gnus-group.el
index 24534a1b66..9bb3ec765f 100644
--- a/lisp/gnus/gnus-group.el
+++ b/lisp/gnus/gnus-group.el
@@ -60,7 +60,7 @@ gnus-no-groups-message
   :type 'string)
 
 (defcustom gnus-keep-same-level nil
-  "Non-nil means that the next newsgroup after the current will be on the same level.
+  "Non-nil means that the newsgroup after this one will be on the same level.
 When you type, for instance, `n' after reading the last article in the
 current newsgroup, you will go to the next newsgroup.  If this variable
 is nil, the next newsgroup will be the next from the group
diff --git a/lisp/gnus/gnus-score.el b/lisp/gnus/gnus-score.el
index 94f2cc310f..33c5803f5a 100644
--- a/lisp/gnus/gnus-score.el
+++ b/lisp/gnus/gnus-score.el
@@ -248,7 +248,7 @@ gnus-default-adaptive-score-alist
 				     (integer :tag "Score"))))))
 
 (defcustom gnus-adaptive-word-length-limit nil
-  "Words of a length lesser than this limit will be ignored when doing adaptive scoring."
+  "Words shorter than this limit will be ignored when doing adaptive scoring."
   :version "22.1"
   :group 'gnus-score-adapt
   :type '(radio (const :format "Unlimited " nil)
diff --git a/lisp/gnus/gnus-sum.el b/lisp/gnus/gnus-sum.el
index 9432eefcb4..3b11a1a8a4 100644
--- a/lisp/gnus/gnus-sum.el
+++ b/lisp/gnus/gnus-sum.el
@@ -744,7 +744,8 @@ gnus-auto-expirable-marks
   :type '(repeat character))
 
 (defcustom gnus-inhibit-user-auto-expire t
-  "If non-nil, user marking commands will not mark an article as expirable, even if the group has auto-expire turned on."
+  "If non-nil, user marking commands will not mark an article as expirable.
+This is true even if the group has auto-expire turned on."
   :version "21.1"
   :group 'gnus-summary
   :type 'boolean)
@@ -1399,7 +1400,7 @@ gnus-newsgroup-process-stack
 (defvar gnus-thread-indent-array nil)
 (defvar gnus-thread-indent-array-level gnus-thread-indent-level)
 (defvar gnus-sort-gathered-threads-function #'gnus-thread-sort-by-number
-  "Function called to sort the articles within a thread after it has been gathered together.")
+  "Function to sort articles within a thread after it has been gathered together.")
 
 (defvar gnus-summary-save-parts-type-history nil)
 (defvar gnus-summary-save-parts-last-directory mm-default-directory)
@@ -1525,7 +1526,7 @@ gnus-last-shell-command
   "Default shell command on article.")
 
 (defvar gnus-newsgroup-agentized nil
-  "Locally bound in each summary buffer to indicate whether the server has been agentized.")
+  "Locally bound in each summary buffer to indicate if server has been agentized.")
 (defvar gnus-newsgroup-begin nil)
 (defvar gnus-newsgroup-end nil)
 (defvar gnus-newsgroup-last-rmail nil)
@@ -1555,7 +1556,7 @@ gnus-newsgroup-reads
 (defvar gnus-newsgroup-expunged-tally nil)
 
 (defvar gnus-newsgroup-marked nil
-  "Sorted list of ticked articles in the current newsgroup (a subset of unread art).")
+  "Sorted list of ticked articles in current newsgroup (a subset of unread art).")
 
 (defvar gnus-newsgroup-spam-marked nil
   "List of ranges of articles that have been marked as spam.")
diff --git a/lisp/gnus/gnus-uu.el b/lisp/gnus/gnus-uu.el
index 70aeac00d7..5980051ee4 100644
--- a/lisp/gnus/gnus-uu.el
+++ b/lisp/gnus/gnus-uu.el
@@ -162,7 +162,7 @@ gnus-uu-ignore-files-by-name
 		 (regexp :format "%v")))
 
 (defcustom gnus-uu-ignore-files-by-type nil
-  "A regular expression saying what files that shouldn't be viewed, based on MIME file type.
+  "Regexp matching files that shouldn't be viewed, based on MIME file type.
 If, for instance, you want gnus-uu to ignore all audio files and all mpegs,
 you could say something like
 
@@ -224,7 +224,7 @@ gnus-uu-tmp-dir
   :type 'directory)
 
 (defcustom gnus-uu-do-not-unpack-archives nil
-  "Non-nil means that gnus-uu won't peek inside archives looking for files to display.
+  "If non-nil, gnus-uu won't peek inside archives looking for files to display.
 Default is nil."
   :group 'gnus-extract-archive
   :type 'boolean)
@@ -265,19 +265,19 @@ gnus-uu-view-with-metamail
   :type 'boolean)
 
 (defcustom gnus-uu-unmark-articles-not-decoded nil
-  "Non-nil means that gnus-uu will mark articles that were unsuccessfully decoded as unread.
+  "If non-nil, gnus-uu will mark unsuccessfully decoded articles as unread.
 Default is nil."
   :group 'gnus-extract
   :type 'boolean)
 
 (defcustom gnus-uu-correct-stripped-uucode nil
-  "Non-nil means that gnus-uu will *try* to fix uuencoded files that have had trailing spaces deleted.
+  "If non-nil, *try* to fix uuencoded files that have had trailing spaces deleted.
 Default is nil."
   :group 'gnus-extract
   :type 'boolean)
 
 (defcustom gnus-uu-save-in-digest nil
-  "Non-nil means that gnus-uu, when asked to save without decoding, will save in digests.
+  "If non-nil, gnus-uu, when asked to save without decoding, will save in digests.
 If this variable is nil, gnus-uu will just save everything in a
 file without any embellishments.  The digesting almost conforms to RFC1153 -
 no easy way to specify any meaningful volume and issue numbers were found,
@@ -1858,7 +1858,7 @@ gnus-uu-post-encode-method
 		(function :tag "Other")))
 
 (defcustom gnus-uu-post-include-before-composing nil
-  "Non-nil means that gnus-uu will ask for a file to encode before you compose the article.
+  "If non-nil, gnus-uu asks for a file to encode before you compose the article.
 If this variable is t, you can either include an encoded file with
 \\[gnus-uu-post-insert-binary-in-article] or have one included for you when you post the article."
   :group 'gnus-extract-post
diff --git a/lisp/gnus/gnus.el b/lisp/gnus/gnus.el
index abe7b1ae76..04adaaba39 100644
--- a/lisp/gnus/gnus.el
+++ b/lisp/gnus/gnus.el
@@ -1195,7 +1195,7 @@ gnus-large-newsgroup
 		 integer))
 
 (defcustom gnus-use-long-file-name (not (memq system-type '(usg-unix-v)))
-  "Non-nil means that the default name of a file to save articles in is the group name.
+  "Non-nil means that the default file name to save articles in is the group name.
 If it's nil, the directory form of the group name is used instead.
 
 If this variable is a list, and the list contains the element
@@ -1545,7 +1545,7 @@ 'gnus-email-address
    ("\\(^\\|:\\)soc.culture.vietnamese\\>" vietnamese-viqr)
    ("\\(^\\|:\\)\\(comp\\|rec\\|alt\\|sci\\|soc\\|news\\|gnu\\|bofh\\)\\>" iso-8859-1))
  :variable-document
- "Alist of regexps (to match group names) and default charsets to be used when reading."
+ "Alist of regexps (to match group names) and default charsets to use when reading."
  :variable-group gnus-charset
  :variable-type '(repeat (list (regexp :tag "Group")
 			       (symbol :tag "Charset")))
@@ -1618,7 +1618,8 @@ 'gnus-email-address
 ;; group parameters for spam processing added by Ted Zlatanov <[email-masked]>
 (defcustom gnus-install-group-spam-parameters t
   "Disable the group parameters for spam detection.
-Enable if `G c' in XEmacs is giving you trouble, and make sure to submit a bug report."
+Enable if `G c' in XEmacs is giving you trouble, and make sure to
+submit a bug report."
   :version "22.1"
   :type 'boolean
   :group 'gnus-start)
diff --git a/lisp/gnus/message.el b/lisp/gnus/message.el
index b6c1c0b071..86800f28cc 100644
--- a/lisp/gnus/message.el
+++ b/lisp/gnus/message.el
@@ -1172,7 +1172,8 @@ message-cite-style
 message-cite-style-* variables.  This variable is intended for
 use in `gnus-posting-styles', such as:
 
-  ((posting-from-work-p) (eval (setq-local message-cite-style message-cite-style-outlook)))"
+  ((posting-from-work-p) (eval (setq-local message-cite-style
+                                           message-cite-style-outlook)))"
   :version "24.1"
   :group 'message-insertion
   :type '(choice (const :tag "Do not override variables" :value nil)
@@ -1199,7 +1200,8 @@ message-cite-style-thunderbird
     (message-yank-cited-prefix  ">")
     (message-yank-empty-prefix  ">")
     (message-citation-line-format "On %D %R %p, %N wrote:"))
-  "Message citation style used by Mozilla Thunderbird.  Use with `message-cite-style'.")
+  "Message citation style used by Mozilla Thunderbird.
+Use with `message-cite-style'.")
 
 (defconst message-cite-style-gmail
   '((message-cite-function  'message-cite-original)
diff --git a/lisp/gnus/nnmail.el b/lisp/gnus/nnmail.el
index 57801d6f9e..6ee29a25cd 100644
--- a/lisp/gnus/nnmail.el
+++ b/lisp/gnus/nnmail.el
@@ -115,7 +115,7 @@ nnmail-crosspost
   :type 'boolean)
 
 (defcustom nnmail-split-fancy-with-parent-ignore-groups nil
-  "Regexp that matches group names to be ignored when applying `nnmail-split-fancy-with-parent'.
+  "Regexp matching group names ignored by `nnmail-split-fancy-with-parent'.
 This can also be a list of regexps."
   :version "22.1"
   :group 'nnmail-split
@@ -124,7 +124,8 @@ nnmail-split-fancy-with-parent-ignore-groups
 		 (repeat :value (".*") regexp)))
 
 (defcustom nnmail-cache-ignore-groups nil
-  "Regexp that matches group names to be ignored when inserting message ids into the cache (`nnmail-cache-insert').
+  "Regexp matching group ignored when inserting message ids into the cache.
+This is used by `nnmail-cache-insert'.
 This can also be a list of regexps."
   :version "22.1"
   :group 'nnmail-split
diff --git a/lisp/gnus/nnmh.el b/lisp/gnus/nnmh.el
index 581a408009..5584dad45f 100644
--- a/lisp/gnus/nnmh.el
+++ b/lisp/gnus/nnmh.el
@@ -46,7 +46,7 @@ nnmh-prepare-save-mail-hook
   "Hook run narrowed to an article before saving.")
 
 (defvoo nnmh-be-safe nil
-  "If non-nil, nnmh will check all articles to make sure whether they are new or not.
+  "If non-nil, nnmh will check all articles to make sure if they are new or not.
 Go through the .nnmh-articles file and compare with the actual
 articles in this folder.  The articles that are \"new\" will be marked
 as unread by Gnus.")
diff --git a/lisp/gnus/nntp.el b/lisp/gnus/nntp.el
index a5c8244792..7d73610267 100644
--- a/lisp/gnus/nntp.el
+++ b/lisp/gnus/nntp.el
@@ -1751,7 +1751,9 @@ nntp-wait-for-string
 ;; ==========================================================================
 
 (defvoo nntp-open-telnet-envuser nil
-  "If non-nil, telnet session (client and server both) will support the ENVIRON option and not prompt for login name.")
+  "If non-nil, telnet session supports the ENVIRON option.
+Don't prompt for login name.  This applies to both client and
+server.")
 
 (defvoo nntp-telnet-shell-prompt "bash\\|[$>] *\r?$"
   "Regular expression to match the shell prompt on the remote machine.")
diff --git a/lisp/ido.el b/lisp/ido.el
index 5758d3fdea..89c70786d2 100644
--- a/lisp/ido.el
+++ b/lisp/ido.el
@@ -842,7 +842,7 @@ ido-rewrite-file-prompt-functions
   max-width - the max width of the resulting dirname; nil means no limit
   prompt    - the basic prompt (e.g. \"Find File: \")
   literal   - the string shown if doing \"literal\" find; set to nil to omit
-  vc-off    - the string shown if version control is inhibited; set to nil to omit
+  vc-off    - the string shown if version control is inhibited; use nil to omit
   prefix    - either nil or a fixed prefix for the dirname
 
 The following variables are available, but should not be changed:
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index d59f2c0ebf..99c014e310 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -1356,7 +1356,7 @@ default-transient-input-method
   :version "28.1")
 
 (defvar current-transient-input-method nil
-  "The current input method temporarily enabled by `activate-transient-input-method'.
+  "Input method temporarily enabled by `activate-transient-input-method'.
 If nil, that means no transient input method is active now.")
 (make-variable-buffer-local 'current-transient-input-method)
 (put 'current-transient-input-method 'permanent-local t)
diff --git a/lisp/language/ethio-util.el b/lisp/language/ethio-util.el
index 55e59ab516..f0df8be7d5 100644
--- a/lisp/language/ethio-util.el
+++ b/lisp/language/ethio-util.el
@@ -113,12 +113,14 @@ ethio-use-colon-for-colon
 variable.")
 
 (defvar ethio-use-three-dot-question nil
-  "Non-nil means associate ASCII question mark with Ethiopic old style question mark (three vertically stacked dots).
+  "If non-nil, associate ASCII question mark with Ethiopic old style question mark.
+The old style question mark is three vertically stacked dots.
+
 If nil, associate ASCII question mark with Ethiopic stylized question
 mark.  All SERA <--> FIDEL converters refer this variable.")
 
 (defvar ethio-quote-vowel-always nil
-  "Non-nil means always put an apostrophe before an isolated vowel (except at word initial) in FIDEL --> SERA conversion.
+  "If non-nil, always put an apostrophe before an isolated vowel (except at word initial) in FIDEL --> SERA conversion.
 If nil, put an apostrophe only between a 6th-form consonant and an
 isolated vowel.")
 
diff --git a/lisp/mail/feedmail.el b/lisp/mail/feedmail.el
index 6effe13986..cc8ab0148b 100644
--- a/lisp/mail/feedmail.el
+++ b/lisp/mail/feedmail.el
@@ -807,7 +807,8 @@ feedmail-fiddle-plex-user-list
 
 feedmail will use this list of fiddle-plexes to manipulate user-specified
 message header fields.  It does this after it has completed all normal
-message header field manipulation and before calling `feedmail-last-chance-hook'.
+message header field manipulation and before calling
+`feedmail-last-chance-hook'.
 
 For an explanation of fiddle-plexes, see the documentation for the
 variable `feedmail-fiddle-plex-blurb'.  In contrast to some other fiddle-plex
@@ -889,13 +890,14 @@ feedmail-spray-address-fiddle-plex-list
 stripped envelope email address (no comments or angle brackets).  The
 function should return an embellished form of the address.
 
-The recipe for sending form letters is:  (1) create a message with all
-addressees on Bcc: headers; (2) tell feedmail to remove Bcc: headers
-before sending the message; (3) create a function which will embellish
-stripped addresses, if desired; (4) define `feedmail-spray-address-fiddle-plex-list'
-appropriately; (5) send the message with `feedmail-enable-spray' set
-non-nil; (6) stand back and watch co-workers wonder at how efficient
-you are at accomplishing inherently inefficient things."
+The recipe for sending form letters is: (1) create a message with
+all addressees on Bcc: headers; (2) tell feedmail to remove Bcc:
+headers before sending the message; (3) create a function which
+will embellish stripped addresses, if desired; (4) define
+`feedmail-spray-address-fiddle-plex-list' appropriately; (5) send
+the message with `feedmail-enable-spray' set non-nil; (6) stand
+back and watch co-workers wonder at how efficient you are at
+accomplishing inherently inefficient things."
   :group 'feedmail-spray
   :type 'sexp ; too complex to be described accurately
   )
diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el
index 3ac5c8f7ae..e5f69a5ae8 100644
--- a/lisp/mh-e/mh-e.el
+++ b/lisp/mh-e/mh-e.el
@@ -3182,7 +3182,7 @@ mh-alias-reloaded-hook
   :package-version '(MH-E . "8.0"))
 
 (defcustom-mh mh-annotate-msg-hook nil
-  "Hook run whenever a message is sent and after the scan lines and message are annotated.
+  "Hook run when a message is sent and after annotating the scan lines and message.
 Hook functions can access the current folder name with
 `mh-current-folder' and obtain the message numbers of the
 annotated messages with `mh-annotate-list'."
diff --git a/lisp/net/imap.el b/lisp/net/imap.el
index 0394f0efea..27c2d869f6 100644
--- a/lisp/net/imap.el
+++ b/lisp/net/imap.el
@@ -190,7 +190,7 @@ imap-shell-program
   :type '(repeat string))
 
 (defcustom imap-process-connection-type nil
-  "Value for `process-connection-type' to use for Kerberos4, GSSAPI, shell, and SSL.
+  "Value for `process-connection-type' to use for Kerberos4, GSSAPI, shell and SSL.
 The `process-connection-type' variable controls the type of device
 used to communicate with subprocesses.  Values are nil to use a
 pipe, or t or `pty' to use a pty.  The value has no effect if the
diff --git a/lisp/net/rcirc.el b/lisp/net/rcirc.el
index c4b68f1be4..6a32fa9255 100644
--- a/lisp/net/rcirc.el
+++ b/lisp/net/rcirc.el
@@ -1507,7 +1507,7 @@ rcirc-last-sender
 (make-variable-buffer-local 'rcirc-last-sender)
 
 (defcustom rcirc-omit-threshold 100
-  "Number of lines since last activity from a nick before `rcirc-omit-responses' are omitted."
+  "Lines since last activity from a nick before `rcirc-omit-responses' are omitted."
   :type 'integer)
 
 (defcustom rcirc-log-process-buffers nil
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index 98537a100f..28c23fa6f7 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -58,8 +58,7 @@ tramp-inline-compress-start-size
 
 ;;;###tramp-autoload
 (defcustom tramp-copy-size-limit 10240
-  "The maximum file size where inline copying is preferred over an \
-out-of-the-band copy.
+  "Maximum file size where inline copying is preferred to an out-of-the-band copy.
 If it is nil, out-of-the-band copy will be used without a check."
   :group 'tramp
   :type '(choice (const nil) integer))
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index 6750a7ff4c..984bfcda0c 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -1022,8 +1022,8 @@ tramp-build-file-name-structure
    5 6 7 8 1))
 
 (defvar tramp-file-name-structure nil ;Initialized when defining `tramp-syntax'!
-  "List of six elements (REGEXP METHOD USER HOST FILE HOP), detailing \
-the Tramp file name structure.
+  "List detailing the Tramp file name structure.
+This is a list of six elements (REGEXP METHOD USER HOST FILE HOP).
 
 The first element REGEXP is a regular expression matching a Tramp file
 name.  The regex should contain parentheses around the method name,
diff --git a/lisp/nxml/nxml-mode.el b/lisp/nxml/nxml-mode.el
index 5bb904e691..080b8c0c6e 100644
--- a/lisp/nxml/nxml-mode.el
+++ b/lisp/nxml/nxml-mode.el
@@ -107,8 +107,10 @@ nxml-prefer-utf-16-little-to-big-endian-flag
 
 (defcustom nxml-default-buffer-file-coding-system nil
   "Default value for `buffer-file-coding-system' for a buffer for a new file.
-A value of nil means use the default value of `buffer-file-coding-system' as normal.
-A buffer's `buffer-file-coding-system' affects what \\[nxml-insert-xml-declaration] inserts."
+A value of nil means use the default value of
+`buffer-file-coding-system' as normal.
+A buffer's `buffer-file-coding-system' affects what
+\\[nxml-insert-xml-declaration] inserts."
   :group 'nxml
   :type 'coding-system)
 
diff --git a/lisp/obsolete/landmark.el b/lisp/obsolete/landmark.el
index df3c5d6cc9..39e0f50e73 100644
--- a/lisp/obsolete/landmark.el
+++ b/lisp/obsolete/landmark.el
@@ -1278,7 +1278,8 @@ landmark-no-payoff
   :group 'landmark)
 (defcustom landmark-max-stall-time 2
   "The maximum number of cycles that the robot can remain stuck in a place.
-After this limit is reached, landmark-random-move is called to push him out of it."
+After this limit is reached, landmark-random-move is called to
+push him out of it."
   :type 'integer
   :group 'landmark)
 
diff --git a/lisp/obsolete/tls.el b/lisp/obsolete/tls.el
index d1b215cbfb..a9d7b84373 100644
--- a/lisp/obsolete/tls.el
+++ b/lisp/obsolete/tls.el
@@ -130,8 +130,10 @@ tls-checktrust
 consider trustworthy, e.g.:
 
 \(setq tls-program
-      \\='(\"gnutls-cli --x509cafile /etc/ssl/certs/ca-certificates.crt -p %p %h\"
-	\"gnutls-cli --x509cafile /etc/ssl/certs/ca-certificates.crt -p %p %h --protocols ssl3\"))"
+      \\='(\"gnutls-cli --x509cafile /etc/ssl/certs/ca-certificates.crt \\
+-p %p %h\"
+        \"gnutls-cli --x509cafile /etc/ssl/certs/ca-certificates.crt \\
+-p %p %h --protocols ssl3\"))"
   :type '(choice (const :tag "Always" t)
 		 (const :tag "Never" nil)
 		 (const :tag "Ask" ask))
diff --git a/lisp/org/ob-R.el b/lisp/org/ob-R.el
index b52c7591ad..0493ebc7db 100644
--- a/lisp/org/ob-R.el
+++ b/lisp/org/ob-R.el
@@ -360,7 +360,7 @@ org-babel-R-write-object-command
             )
     }
 }(object=%s,transfer.file=\"%s\")"
-  "A template for an R command to evaluate a block of code and write the result to a file.
+  "Template for an R command to evaluate a block of code and write result to file.
 
 Has four %s escapes to be filled in:
 1. Row names, \"TRUE\" or \"FALSE\"
diff --git a/lisp/org/org-agenda.el b/lisp/org/org-agenda.el
index 82bf1b23f9..822276d3d9 100644
--- a/lisp/org/org-agenda.el
+++ b/lisp/org/org-agenda.el
@@ -7495,7 +7495,8 @@ org-agenda-filter-by-category
   "Filter lines in the agenda buffer that have a specific category.
 The category is that of the current line.
 With a `\\[universal-argument]' prefix argument, exclude the lines of that category.
-When there is already a category filter in place, this command removes the filter."
+When there is already a category filter in place, this command removes the
+filter."
   (interactive "P")
   (if (and org-agenda-filtered-by-category
 	   org-agenda-category-filter)
diff --git a/lisp/org/org-attach.el b/lisp/org/org-attach.el
index 1ed305c9ff..8b0c05e063 100644
--- a/lisp/org/org-attach.el
+++ b/lisp/org/org-attach.el
@@ -181,7 +181,7 @@ org-attach-id-to-path-function-list
   :type '(repeat (function :tag "Function with ID as input")))
 
 (defvar org-attach-after-change-hook nil
-  "Hook to be called when files have been added or removed to the attachment folder.")
+  "Hook called when files have been added or removed to the attachment folder.")
 
 (defvar org-attach-open-hook nil
   "Hook that is invoked by `org-attach-open'.
diff --git a/lisp/org/org-indent.el b/lisp/org/org-indent.el
index 5171919465..a6a9fe145c 100644
--- a/lisp/org/org-indent.el
+++ b/lisp/org/org-indent.el
@@ -87,15 +87,13 @@ org-indent-boundary-char
   :type 'character)
 
 (defcustom org-indent-mode-turns-off-org-adapt-indentation t
-  "Non-nil means setting the variable `org-indent-mode' will \
-turn off indentation adaptation.
+  "Non-nil means setting `org-indent-mode' will turn off indentation adaptation.
 For details see the variable `org-adapt-indentation'."
   :group 'org-indent
   :type 'boolean)
 
 (defcustom org-indent-mode-turns-on-hiding-stars t
-  "Non-nil means setting the variable `org-indent-mode' will \
-turn on `org-hide-leading-stars'."
+  "Non-nil means setting `org-indent-mode' will turn on `org-hide-leading-stars'."
   :group 'org-indent
   :type 'boolean)
 
diff --git a/lisp/org/org-protocol.el b/lisp/org/org-protocol.el
index 55a534d0dc..06f50061a4 100644
--- a/lisp/org/org-protocol.el
+++ b/lisp/org/org-protocol.el
@@ -181,7 +181,8 @@ org-protocol-project-alist
   :working-directory - the local working directory.  This is, what base-url will
                        be replaced with.
   :redirects         - A list of cons cells, each of which maps a regular
-                       expression to match to a path relative to :working-directory.
+                       expression to match to a path relative to
+                       :working-directory.
 
 Example:
 
@@ -202,7 +203,8 @@ org-protocol-project-alist
           :working-directory \"~/site/content/post/\"
           :online-suffix \".html\"
           :working-suffix \".md\"
-          :rewrites ((\"\\(https://site.com/[0-9]+/[0-9]+/[0-9]+/\\)\" . \".md\")))))
+          :rewrites ((\"\\(https://site.com/[0-9]+/[0-9]+/[0-9]+/\\)\"
+                      . \".md\")))))

    The last line tells `org-protocol-open-source' to open
diff --git a/lisp/org/org.el b/lisp/org/org.el
index 5dc9fa9d8d..f597da6885 100644
--- a/lisp/org/org.el
+++ b/lisp/org/org.el
@@ -4177,7 +4177,8 @@ org-stamp-time-of-day-regexp
   "Regular expression to match a timestamp time or time range.
 After a match, the following groups carry important information:
 0  the full match
-1  date plus weekday, for back referencing to make sure both times are on the same day
+1  date plus weekday, for back referencing to
+     make sure both times are on the same day
 2  the first time, range or not
 4  the second time, if it is a range.")
 
diff --git a/lisp/progmodes/cc-vars.el b/lisp/progmodes/cc-vars.el
index 9e6f9527ca..8772ed0632 100644
--- a/lisp/progmodes/cc-vars.el
+++ b/lisp/progmodes/cc-vars.el
@@ -575,7 +575,8 @@ c-doc-comment-style
 
  javadoc -- Javadoc style for \"/** ... */\" comments (default in Java mode).
  autodoc -- Pike autodoc style for \"//! ...\" comments (default in Pike mode).
- gtkdoc  -- GtkDoc style for \"/** ... **/\" comments (default in C and C++ modes).
+ gtkdoc  -- GtkDoc style for \"/** ... **/\" comments
+						   (default in C and C++ modes).
  doxygen -- Doxygen style.
 
 The value may also be a list of doc comment styles, in which case all
diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el
index ed9b234d69..f67ec6b6cd 100644
--- a/lisp/progmodes/cperl-mode.el
+++ b/lisp/progmodes/cperl-mode.el
@@ -232,7 +232,10 @@ cperl-indent-wrt-brace
   :group 'cperl-indentation-details)
 
 (defcustom cperl-indent-subs-specially t
-  "Non-nil means indent subs that are inside other blocks (hash values, for example) relative to the beginning of the \"sub\" keyword, rather than relative to the statement that contains the declaration."
+  "If non-nil, indent subs inside other blocks relative to \"sub\" keyword.
+If nil, indent them relative to the statement that contains the
+declaration.
+This applies to hash values, for example."
   :type 'boolean
   :group 'cperl-indentation-details)
 
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index fa360a8f3f..90b0263fe1 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -682,7 +682,8 @@ elisp--xref-make-xref
 	     (xref-make-elisp-location symbol type file)))
 
 (defvar elisp-xref-find-def-functions nil
-  "List of functions to be run from `elisp--xref-find-definitions' to add additional xrefs.
+  "List of functions to be run from `elisp--xref-find-definitions'.
+These are used to add additional xrefs.
 Called with one arg; the symbol whose definition is desired.
 Each function should return a list of xrefs, or nil; the first
 non-nil result supersedes the xrefs produced by
diff --git a/lisp/progmodes/flymake-proc.el b/lisp/progmodes/flymake-proc.el
index 152dc725c7..744c110f6b 100644
--- a/lisp/progmodes/flymake-proc.el
+++ b/lisp/progmodes/flymake-proc.el
@@ -120,8 +120,10 @@ flymake-proc-allowed-file-name-masks
   REGEXP INIT [CLEANUP [NAME]]
 REGEXP is a regular expression that matches a file name.
 INIT is the init function to use.
-CLEANUP is the cleanup function to use, default `flymake-proc-simple-cleanup'.
-NAME is the file name function to use, default `flymake-proc-get-real-file-name'."
+CLEANUP is the cleanup function to use, default
+  `flymake-proc-simple-cleanup'.
+NAME is the file name function to use, default
+  `flymake-proc-get-real-file-name'."
   :group 'flymake
   :type '(alist :key-type (regexp :tag "File regexp")
                 :value-type
diff --git a/lisp/progmodes/hideif.el b/lisp/progmodes/hideif.el
index 7cbc9708fc..0ca2ff53b2 100644
--- a/lisp/progmodes/hideif.el
+++ b/lisp/progmodes/hideif.el
@@ -153,8 +153,8 @@ hide-ifdef-expand-reinclusion-protection
 undefined, and so nothing is hidden.  The next time we visit it, everything will
 be hidden.
 
-This behavior is generally undesirable.  If this option is non-nil, the outermost
-#if is always visible."
+This behavior is generally undesirable.  If this option is non-nil, the
+outermost #if is always visible."
   :type 'boolean
   :version "25.1")
 
diff --git a/lisp/progmodes/ruby-mode.el b/lisp/progmodes/ruby-mode.el
index fbc6e424eb..8cb0350dc0 100644
--- a/lisp/progmodes/ruby-mode.el
+++ b/lisp/progmodes/ruby-mode.el
@@ -75,7 +75,7 @@ ruby-block-mid-keywords
 
 (defconst ruby-block-mid-re
   (regexp-opt ruby-block-mid-keywords)
-  "Regexp to match where the indentation gets shallower in middle of block statements.")
+  "Regexp for where the indentation gets shallower in middle of block statements.")
 
 (defconst ruby-block-op-keywords
   '("and" "or" "not")
diff --git a/lisp/progmodes/verilog-mode.el b/lisp/progmodes/verilog-mode.el
index b1abefe534..f6e95b9cb6 100644
--- a/lisp/progmodes/verilog-mode.el
+++ b/lisp/progmodes/verilog-mode.el
@@ -10112,7 +10112,8 @@ verilog-module-filenames
 ;; A modi is:  [module-name-string file-name begin-point]
 
 (defvar verilog-cache-enabled t
-  "Non-nil enables caching of signals, etc.  Set to nil for debugging to make things SLOW!")
+  "Non-nil enables caching of signals, etc.
+Set to nil for debugging to make things SLOW!")
 
 (defvar verilog-modi-cache-list nil
   "Cache of ((Module Function) Buf-Tick Buf-Modtime Func-Returns)...
diff --git a/lisp/ses.el b/lisp/ses.el
index bfafc132bf..2a28ad3add 100644
--- a/lisp/ses.el
+++ b/lisp/ses.el
@@ -430,7 +430,8 @@ ses-get-cell
   local-printer-list)
 
 (defmacro ses-cell-symbol (row &optional col)
-  "From a CELL or a pair (ROW,COL), get the symbol that names the local-variable holding its value.  (0,0) => A1."
+  "Return symbol of the local-variable holding value of CELL or pair (ROW,COL).
+For example, (0,0) => A1."
   (declare (debug t))
   `(ses-cell--symbol ,(if col `(ses-get-cell ,row ,col) row)))
 (put 'ses-cell-symbol 'safe-function t)
diff --git a/lisp/simple.el b/lisp/simple.el
index 6059c23a14..1d4ac01638 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -2195,7 +2195,8 @@ minibuffer-history-case-insensitive-variables
   "Minibuffer history variables for which matching should ignore case.
 If a history variable is a member of this list, then the
 \\[previous-matching-history-element] and \\[next-matching-history-element]\
- commands ignore case when searching it, regardless of `case-fold-search'."
+ commands ignore case when searching it,
+regardless of `case-fold-search'."
   :type '(repeat variable)
   :group 'minibuffer)
 
diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index 1327bde908..cd152fb092 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -841,8 +841,10 @@ tab-bar-close-last-tab-choice
   "Defines what to do when the last tab is closed.
 If nil, do nothing and show a message, like closing the last window or frame.
 If `delete-frame', delete the containing frame, as a web browser would do.
-If `tab-bar-mode-disable', disable tab-bar-mode so that tabs no longer show in the frame.
-If the value is a function, call that function with the tab to be closed as an argument."
+If `tab-bar-mode-disable', disable tab-bar-mode so that tabs no longer show in
+the frame.
+If the value is a function, call that function with the tab to be closed as an
+ argument."
   :type '(choice (const    :tag "Do nothing and show message" nil)
                  (const    :tag "Close the containing frame" delete-frame)
                  (const    :tag "Disable tab-bar-mode" tab-bar-mode-disable)
diff --git a/lisp/term.el b/lisp/term.el
index 2e69af0735..d73a9b0d01 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -365,8 +365,8 @@ term-scroll-start
 (defvar-local term-scroll-end nil
   "Bottom-most line (inclusive) of the scrolling region.
 `term-scroll-end' must be in the range [0,term-height).  In addition, its
-value has to be greater than `term-scroll-start', i.e. one line scroll regions are
-not allowed.")
+value has to be greater than `term-scroll-start', i.e. one line scroll regions
+are not allowed.")
 (defvar term-pager-count nil
   "Number of lines before we need to page; if nil, paging is disabled.")
 (defvar term-saved-cursor nil)
diff --git a/lisp/textmodes/reftex-vars.el b/lisp/textmodes/reftex-vars.el
index c9fd19d232..b4b7db579c 100644
--- a/lisp/textmodes/reftex-vars.el
+++ b/lisp/textmodes/reftex-vars.el
@@ -741,8 +741,8 @@ reftex-special-environment-functions
 boundary for backwards searches which should be observed.
 
 Here is an example.  The LaTeX package linguex.sty defines list macros
-`\\ex.', `\\a.', etc for lists which are terminated by `\\z.' or an empty
-line.
+`\\ex.', `\\a.', etc for lists which are terminated by `\\z.' or an
+empty line.
 
     \\ex.  \\label{ex:12} Some text in an exotic language ...
           \\a. \\label{ex:13} more stuff
@@ -766,10 +766,12 @@ reftex-special-environment-functions
        (save-excursion
          ;; Search for any of the linguex item macros at the beginning of a line
          (if (re-search-backward
-              \"^[ \\t]*\\\\(\\\\\\\\\\\\(ex\\\\|a\\\\|b\\\\|c\\\\|d\\\\|e\\\\|f\\\\)g?\\\\.\\\\)\" bound t)
+              (concat \"^[ \\t]*\\\\(\\\\\\\\\\\\(ex\\\\|a\\\\|b\"
+                      \"\\\\|c\\\\|d\\\\|e\\\\|f\\\\)g?\\\\.\\\\)\")
+              bound t)
              (progn
                (setq p1 (match-beginning 1))
-               ;; Make sure no empty line or \\z. is between us and the item macro
+               ;; Make sure no empty line or \\z. is between us and item macro
                (if (re-search-forward \"\\n[ \\t]*\\n\\\\|\\\\\\\\z\\\\.\" pos t)
                    ;; Return nil because list was already closed
                    nil
diff --git a/lisp/textmodes/table.el b/lisp/textmodes/table.el
index e42615e515..3582f15731 100644
--- a/lisp/textmodes/table.el
+++ b/lisp/textmodes/table.el
@@ -853,10 +853,12 @@ table-heighten-timer
   "Timer id for deferred cell update.")
 (defvar table-inhibit-update nil
   "Non-nil inhibits implicit cell and cache updates.
-It inhibits `table-with-cache-buffer' to update data in both direction, cell to cache and cache to cell.")
+It inhibits `table-with-cache-buffer' to update data in both
+direction, cell to cache and cache to cell.")
 (defvar table-inhibit-auto-fill-paragraph nil
   "Non-nil inhibits auto fill paragraph when `table-with-cache-buffer' exits.
-This is always set to nil at the entry to `table-with-cache-buffer' before executing body forms.")
+This is always set to nil at the entry to
+`table-with-cache-buffer' before executing body forms.")
 (defvar table-mode-indicator nil
   "For mode line indicator")
 ;; This is not a real minor-mode but placed in the minor-mode-alist
@@ -957,7 +959,7 @@ table-command-remap-alist
     (describe-bindings . *table--cell-describe-bindings)
     (dabbrev-expand . *table--cell-dabbrev-expand)
     (dabbrev-completion . *table--cell-dabbrev-completion))
-  "List of cons cells consisting of (ORIGINAL-COMMAND . TABLE-VERSION-OF-THE-COMMAND).")
+  "List of the form (ORIGINAL-COMMAND . TABLE-VERSION-OF-THE-COMMAND).")
 
 (defvar table-command-list
   ;; Construct the real contents of the `table-command-list'.
diff --git a/lisp/vc/ediff-diff.el b/lisp/vc/ediff-diff.el
index ccf5a7807f..adb6ce8053 100644
--- a/lisp/vc/ediff-diff.el
+++ b/lisp/vc/ediff-diff.el
@@ -149,7 +149,7 @@ ediff-auto-refine
 Use `setq-default' if setting it in .emacs")
 
 (ediff-defvar-local ediff-ignore-similar-regions nil
-  "If t, skip over difference regions that differ only in the white space and line breaks.
+  "If t, skip difference regions that differ only in white space and line breaks.
 This variable can be set either in .emacs or toggled interactively.
 Use `setq-default' if setting it in .emacs")
 
diff --git a/lisp/vc/ediff-init.el b/lisp/vc/ediff-init.el
index 04926af16e..b5c2c45583 100644
--- a/lisp/vc/ediff-init.el
+++ b/lisp/vc/ediff-init.el
@@ -432,7 +432,7 @@ ediff-after-setup-control-frame-hook
   :type 'hook
   :group 'ediff-hook)
 (defcustom ediff-startup-hook nil
-  "Hooks to run in the control buffer after Ediff has been set up and is ready for the job."
+  "Hooks to run in the control buffer after Ediff has been set up and is ready."
   :type 'hook
   :group 'ediff-hook)
 (defcustom ediff-select-hook nil
@@ -480,7 +480,7 @@ ediff-quit-hook
   :type 'hook
   :group 'ediff-hook)
 (defcustom ediff-cleanup-hook nil
-  "Hooks to run on exiting Ediff but before killing the control and variant buffers."
+  "Hooks to run on exiting Ediff, before killing the control and variant buffers."
   :type 'hook
   :group 'ediff-hook)
 
@@ -1268,7 +1268,7 @@ ediff-temp-file-mode
 ;; Metacharacters that have to be protected from the shell when executing
 ;; a diff/diff3 command.
 (defcustom ediff-metachars "[ \t\n!\"#$&'()*;<=>?[\\^`{|~]"
-  "Regexp that matches characters that must be quoted with `\\' in shell command line.
+  "Regexp matching characters that must be quoted with `\\' in shell command line.
 This default should work without changes."
   :type 'regexp
   :group 'ediff)
diff --git a/lisp/vc/ediff-merg.el b/lisp/vc/ediff-merg.el
index 22656761d9..1c1d5219c7 100644
--- a/lisp/vc/ediff-merg.el
+++ b/lisp/vc/ediff-merg.el
@@ -70,7 +70,7 @@ ediff-combination-pattern
   :group 'ediff-merge)
 
 (defcustom ediff-show-clashes-only nil
-  "If t, show only those diff regions where both buffers disagree with the ancestor.
+  "If t, show only diff regions where both buffers disagree with the ancestor.
 This means that regions that have status prefer-A or prefer-B will be
 skipped over.  A value of nil means show all regions."
   :type 'boolean
diff --git a/lisp/vc/ediff-mult.el b/lisp/vc/ediff-mult.el
index b48377815a..3d79630f3b 100644
--- a/lisp/vc/ediff-mult.el
+++ b/lisp/vc/ediff-mult.el
@@ -181,7 +181,7 @@ ediff-recurse-to-subdirectories
 (defvar ediff-filtering-regexp-history nil "")
 
 (defcustom ediff-default-filtering-regexp nil
-  "The default regular expression used as a filename filter in multifile comparisons.
+  "Default regular expression used as a filename filter in multifile comparisons.
 Should be a sexp.  For instance (car ediff-filtering-regexp-history) or nil."
   :type 'sexp                           ; yuck - why not just a regexp?
   :risky t)
diff --git a/lisp/vc/ediff-wind.el b/lisp/vc/ediff-wind.el
index c68dc71884..3d90ccb1cb 100644
--- a/lisp/vc/ediff-wind.el
+++ b/lisp/vc/ediff-wind.el
@@ -182,7 +182,7 @@ ediff-mouse-pixel-position
 
 ;; not used for now
 (defvar ediff-mouse-pixel-threshold 30
-  "If the user moves mouse more than this many pixels, Ediff won't warp mouse into control window.")
+  "If mouse moved more than this many pixels, don't warp mouse into control window.")
 
 (defcustom ediff-grab-mouse t
   "If t, Ediff will always grab the mouse and put it in the control frame.
diff --git a/lisp/vc/smerge-mode.el b/lisp/vc/smerge-mode.el
index 13f875b192..5c41761a04 100644
--- a/lisp/vc/smerge-mode.el
+++ b/lisp/vc/smerge-mode.el
@@ -925,7 +925,7 @@ smerge-refine-forward-function
   This only matters if `smerge-refine-weight-hack' is nil.")
 
 (defvar smerge-refine-ignore-whitespace t
-  "If non-nil, indicate that `smerge-refine' should try to ignore change in whitespace.")
+  "If non-nil, `smerge-refine' should try to ignore change in whitespace.")
 
 (defvar smerge-refine-weight-hack t
   "If non-nil, pass to diff as many lines as there are chars in the region.
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index b3b0583966..a73774d090 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2385,8 +2385,9 @@ vc-retrieve-tag
 ;; for the root directory.
 (defvar vc-log-short-style '(directory)
   "Whether or not to show a short log.
-If it contains `directory' then if the fileset contains a directory show a short log.
-If it contains `file' then show short logs for files.
+If it contains `directory', show a short log if the fileset
+contains a directory.
+If it contains `file', show short logs for files.
 Not all VC backends support short logs!")
 
 (defvar log-view-vc-fileset)
diff --git a/lisp/view.el b/lisp/view.el
index 6f576f8c04..c1b788a739 100644
--- a/lisp/view.el
+++ b/lisp/view.el
@@ -141,7 +141,8 @@ view-return-to-alist
 (put 'view-return-to-alist 'permanent-local t)
 
 (defvar view-exit-action nil
-  "If non-nil, a function with one argument (a buffer) called when finished viewing.
+  "If non-nil, a function called when finished viewing.
+The function should take one argument (a buffer).
 Commands like \\[view-file] and \\[view-file-other-window] may
 set this to bury or kill the viewed buffer.
 Observe that the buffer viewed might not appear in any window at
-- 
2.29.2