17 files changed, 82 insertions, 85 deletions

diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 4f01918bdb9..13b72196565 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -677,7 +677,7 @@ Each element is (INDEX . VALUE)")
 (byte-defop 112  1 byte-current-buffer)
 (byte-defop 113  0 byte-set-buffer)
 (byte-defop 114  0 byte-save-current-buffer
-  "To make a binding to record the current buffer")
+  "to make a binding to record the current buffer")
 (byte-defop 115  0 byte-set-mark-OBSOLETE)
 (byte-defop 116  1 byte-interactive-p-OBSOLETE)
 
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index b5581aa3fbb..e4b800786cc 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -2134,7 +2134,7 @@ buffer, otherwise stop after the first error."
     (checkdoc-ispell-init)
     (unless checkdoc-spellcheck-documentation-flag
       ;; this happens when (checkdoc-ispell-init) can't start `ispell-program-name'
-      (user-error "No spellchecker installed: check the variable `ispell-program-name'."))
+      (user-error "No spellchecker installed: check the variable `ispell-program-name'"))
     (save-excursion
       (skip-chars-forward "^a-zA-Z")
       (let (word sym case-fold-search err word-beginning word-end)
diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index bb10194a946..4408bb58464 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -767,7 +767,7 @@ The result of the body appears to the compiler as a quoted constant."
   "Eval EXPR and choose among clauses on that value.
 Each clause looks like (KEYLIST BODY...).  EXPR is evaluated and
 compared against each key in each KEYLIST; the corresponding BODY
-is evaluated.  If no clause succeeds, cl-case returns nil.  A
+is evaluated.  If no clause succeeds, this macro returns nil.  A
 single non-nil atom may be used in place of a KEYLIST of one
 atom.  A KEYLIST of t or `otherwise' is allowed only in the final
 clause, and matches if no other keys match.  Key values are
@@ -806,10 +806,10 @@ compared by `eql'.
 
 ;;;###autoload
 (defmacro cl-typecase (expr &rest clauses)
-  "Evals EXPR, chooses among clauses on that value.
+  "Eval EXPR and choose among clauses on that value.
 Each clause looks like (TYPE BODY...).  EXPR is evaluated and, if it
 satisfies TYPE, the corresponding BODY is evaluated.  If no clause succeeds,
-cl-typecase returns nil.  A TYPE of t or `otherwise' is allowed only in the
+this macro returns nil.  A TYPE of t or `otherwise' is allowed only in the
 final clause, and matches if no other keys match.
 \n(fn EXPR (TYPE BODY...)...)"
   (declare (indent 1)
@@ -2701,7 +2701,7 @@ pairs for that slot.
 Supported keywords for slots are:
 - `:read-only':  If this has a non-nil value, that slot cannot be set via `setf'.
 - `:documentation': this is a docstring describing the slot.
-- `:type': the type of the field; currently unused.
+- `:type': the type of the field; currently only used for documentation.
 
 \(fn NAME &optional DOCSTRING &rest SLOTS)"
   (declare (doc-string 2) (indent 1)
diff --git a/lisp/emacs-lisp/elp.el b/lisp/emacs-lisp/elp.el
index 7dd3cbd1a21..f68c0faf09d 100644
--- a/lisp/emacs-lisp/elp.el
+++ b/lisp/emacs-lisp/elp.el
@@ -238,7 +238,7 @@ FUNSYM must be a symbol of a defined function."
     ;; The info vector data structure is a 2 element vector.  The 0th
     ;; element is the call-count, i.e. the total number of times this
     ;; function has been entered.  This value is bumped up on entry to
-    ;; the function so that non-local exists are still recorded. TBD:
+    ;; the function so that non-local exits are still recorded. TBD:
     ;; I haven't tested non-local exits at all, so no guarantees.
     ;;
     ;; The 1st element is the total amount of time in seconds that has
diff --git a/lisp/emacs-lisp/generator.el b/lisp/emacs-lisp/generator.el
index 27ed29925b3..ba344eb5150 100644
--- a/lisp/emacs-lisp/generator.el
+++ b/lisp/emacs-lisp/generator.el
@@ -59,7 +59,7 @@
 ;; This raw form of iteration is general, but a bit awkward to use, so
 ;; this library also provides some convenience functions:
 ;;
-;; `iter-do' is like `cl-do', except that instead of walking a list,
+;; `iter-do' is like `dolist', except that instead of walking a list,
 ;; it walks an iterator.  `cl-loop' is also extended with a new
 ;; keyword, `iter-by', that iterates over an iterator.
 ;;
@@ -67,7 +67,7 @@
 ;;; Implementation:
 
 ;;
-;; The internal cps transformation code uses the cps- namespace.
+;; The internal CPS transformation code uses the cps- namespace.
 ;; Iteration functions use the `iter-' namespace.  Generator functions
 ;; are somewhat less efficient than conventional elisp routines,
 ;; although we try to avoid CPS transformation on forms that do not
@@ -89,13 +89,13 @@
   `(gensym (format ,fmt ,@args)))
 
 (defvar cps--dynamic-wrappers '(identity)
-  "List of transformer functions to apply to atomic forms we
-evaluate in CPS context.")
+  "List of functions to apply to atomic forms.
+These are transformer functions applied to atomic forms evaluated
+in CPS context.")
 
 (defconst cps-standard-special-forms
   '(setq setq-default throw interactive)
-  "List of special forms that we treat just like ordinary
-  function applications." )
+  "List of special forms treated just like ordinary function applications." )
 
 (defun cps--trace-funcall (func &rest args)
   (message "%S: args=%S" func args)
@@ -118,17 +118,15 @@ evaluate in CPS context.")
        (error "%s not supported in generators" ,function)))
 
 (defmacro cps--with-value-wrapper (wrapper &rest body)
-  "Continue generating CPS code with an atomic-form wrapper
-to the current stack of such wrappers.  WRAPPER is a function that
-takes a form and returns a wrapped form.
+  "Evaluate BODY with WRAPPER added to the stack of atomic-form wrappers.
+WRAPPER is a function that takes an atomic form and returns a wrapped form.
 
 Whenever we generate an atomic form (i.e., a form that can't
 `iter-yield'), we first (before actually inserting that form in our
 generated code) pass that form through all the transformer
 functions.  We use this facility to wrap forms that can transfer
 control flow non-locally in goo that diverts this control flow to
-the CPS state machinery.
-"
+the CPS state machinery."
   (declare (indent 1))
   `(let ((cps--dynamic-wrappers
           (cons
@@ -153,7 +151,7 @@ DYNAMIC-VAR bound to STATIC-VAR."
      ,@body))
 
 (defun cps--add-state (kind body)
-  "Create a new CPS state with body BODY and return the state's name."
+  "Create a new CPS state of KIND with BODY and return the state's name."
   (declare (indent 1))
   (let ((state (cps--gensym "cps-state-%s-" kind)))
     (push (list state body cps--cleanup-function) cps--states)
@@ -170,14 +168,12 @@ DYNAMIC-VAR bound to STATIC-VAR."
     (and (fboundp handler) handler)))
 
 (defvar cps-inhibit-atomic-optimization nil
-  "When non-nil, always rewrite forms into cps even when they
-don't yield.")
+  "When non-nil, always rewrite forms into CPS even when they don't yield.")
 
 (defvar cps--yield-seen)
 
 (defun cps--atomic-p (form)
-  "Return whether the given form never yields."
-
+  "Return nil if FORM can yield, non-nil otherwise."
   (and (not cps-inhibit-atomic-optimization)
        (let* ((cps--yield-seen))
          (ignore (macroexpand-all
@@ -649,8 +645,8 @@ modified copy."
 (defun iter-yield (value)
   "When used inside a generator, yield control to caller.
 The caller of `iter-next' receives VALUE, and the next call to
-`iter-next' resumes execution at the previous
-`iter-yield' point."
+`iter-next' resumes execution with the form immediately following this
+`iter-yield' call."
   (identity value)
   (error "`iter-yield' used outside a generator"))
 
diff --git a/lisp/emacs-lisp/gv.el b/lisp/emacs-lisp/gv.el
index 3ab49293e90..096036a0ffa 100644
--- a/lisp/emacs-lisp/gv.el
+++ b/lisp/emacs-lisp/gv.el
@@ -38,7 +38,7 @@
 ;;
 ;; Instead, we use here a higher-order approach: instead
 ;; of a 5-tuple, a place-expander returns a function.
-;; If you think about types, the old approach return things of type
+;; If you think about types, the old approach returns things of type
 ;;    {vars: List Var, values: List Exp,
 ;;     stores: List Var, getter: Exp, setter: Exp}
 ;; whereas the new approach returns a function of type
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 3b0f5493eeb..98c44161ad0 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -535,7 +535,7 @@ This will generate compile-time constants from BINDINGS."
 
 ;; Support backtrace mode.
 (defconst lisp-el-font-lock-keywords-for-backtraces lisp-el-font-lock-keywords
-  "Default highlighting from Emacs Lisp mod used in Backtrace mode.")
+  "Default highlighting from Emacs Lisp mode used in Backtrace mode.")
 (defconst lisp-el-font-lock-keywords-for-backtraces-1 lisp-el-font-lock-keywords-1
   "Subdued highlighting from Emacs Lisp mode used in Backtrace mode.")
 (defconst lisp-el-font-lock-keywords-for-backtraces-2
diff --git a/lisp/image-mode.el b/lisp/image-mode.el
index 22d7d913141..fbce1193cd0 100644
--- a/lisp/image-mode.el
+++ b/lisp/image-mode.el
@@ -418,24 +418,40 @@ call."
 
 (defvar image-mode-map
   (let ((map (make-sparse-keymap)))
+
+    ;; Toggling keys
     (define-key map "\C-c\C-c" 'image-toggle-display)
     (define-key map "\C-c\C-x" 'image-toggle-hex-display)
-    (define-key map (kbd "SPC")       'image-scroll-up)
-    (define-key map (kbd "S-SPC")     'image-scroll-down)
-    (define-key map (kbd "DEL")       'image-scroll-down)
-    (define-key map (kbd "RET")       'image-toggle-animation)
+
+    ;; Transformation keys
+    (define-key map "sf" 'image-mode-fit-frame)
+    (define-key map "sh" 'image-transform-fit-to-height)
+    (define-key map "sw" 'image-transform-fit-to-width)
+    (define-key map "sr" 'image-transform-set-rotation)
+    (define-key map "s0" 'image-transform-reset)
+    (define-key map "ss" 'image-transform-set-scale)
+
+    ;; Multi-frame keys
+    (define-key map (kbd "RET") 'image-toggle-animation)
     (define-key map "F" 'image-goto-frame)
     (define-key map "f" 'image-next-frame)
     (define-key map "b" 'image-previous-frame)
-    (define-key map "n" 'image-next-file)
-    (define-key map "p" 'image-previous-file)
     (define-key map "a+" 'image-increase-speed)
     (define-key map "a-" 'image-decrease-speed)
     (define-key map "a0" 'image-reset-speed)
     (define-key map "ar" 'image-reverse-speed)
+
+    ;; File keys
+    (define-key map "n" 'image-next-file)
+    (define-key map "p" 'image-previous-file)
     (define-key map "w" 'image-mode-copy-file-name-as-kill)
     (define-key map "m" 'image-mode-mark-file)
     (define-key map "u" 'image-mode-unmark-file)
+
+    ;; Scrolling keys
+    (define-key map (kbd "SPC")   'image-scroll-up)
+    (define-key map (kbd "S-SPC") 'image-scroll-down)
+    (define-key map (kbd "DEL")   'image-scroll-down)
     (define-key map [remap forward-char] 'image-forward-hscroll)
     (define-key map [remap backward-char] 'image-backward-hscroll)
     (define-key map [remap right-char] 'image-forward-hscroll)
@@ -452,6 +468,7 @@ call."
     (define-key map [remap move-end-of-line] 'image-eol)
     (define-key map [remap beginning-of-buffer] 'image-bob)
     (define-key map [remap end-of-buffer] 'image-eob)
+
     (easy-menu-define image-mode-menu map "Menu for Image mode."
       '("Image"
         ["Show as Text" image-toggle-display :active t
@@ -459,17 +476,15 @@ call."
     ["Show as Hex" image-toggle-hex-display :active t
      :help "Show image as hex"]
         "--"
+        ["Fit Frame to Image" image-mode-fit-frame :active t
+         :help "Resize frame to match image"]
         ["Fit to Window Height" image-transform-fit-to-height
-         :visible (eq image-type 'imagemagick)
          :help "Resize image to match the window height"]
         ["Fit to Window Width" image-transform-fit-to-width
-         :visible (eq image-type 'imagemagick)
          :help "Resize image to match the window width"]
         ["Rotate Image..." image-transform-set-rotation
-         :visible (eq image-type 'imagemagick)
          :help "Rotate the image"]
         ["Reset Transformations" image-transform-reset
-         :visible (eq image-type 'imagemagick)
          :help "Reset all image transformations"]
         "--"
         ["Show Thumbnails"
@@ -486,9 +501,6 @@ call."
          :active buffer-file-name
          :help "Copy the current file name to the kill ring"]
         "--"
-        ["Fit Frame to Image" image-mode-fit-frame :active t
-         :help "Resize frame to match image"]
-        "--"
         ["Animate Image" image-toggle-animation :style toggle
          :selected (let ((image (image-get-display-property)))
                      (and image (image-animate-timer image)))
@@ -767,11 +779,12 @@ was inserted."
          props image)
 
     ;; Get the rotation data from the file, if any.
-    (setq image-transform-rotation
-          (or (exif-orientation
-               (ignore-error exif-error
-                 (exif-parse-buffer)))
-              0.0))
+    (when (zerop image-transform-rotation) ; don't reset modified value
+      (setq image-transform-rotation
+            (or (exif-orientation
+                 (ignore-error exif-error
+                   (exif-parse-buffer)))
+                0.0)))
 
     ;; :scale 1: If we do not set this, create-image will apply
     ;; default scaling based on font size.
@@ -1250,8 +1263,7 @@ Do this for an image of type `imagemagick' to make sure that the
 elisp code matches the way ImageMagick computes the bounding box
 of a rotated image."
   (when (and (not (numberp image-transform-resize))
-             (boundp 'image-type)
-             (eq image-type 'imagemagick))
+             (boundp 'image-type))
     (let ((size (image-display-size (image-get-display-property) t)))
       (cond ((eq image-transform-resize 'fit-width)
              (cl-assert (= (car size)
@@ -1268,10 +1280,7 @@ of a rotated image."
   "Return rescaling/rotation properties for image SPEC.
 These properties are determined by the Image mode variables
 `image-transform-resize' and `image-transform-rotation'.  The
-return value is suitable for appending to an image spec.
-
-Rescaling and rotation properties only take effect if Emacs is
-compiled with ImageMagick support."
+return value is suitable for appending to an image spec."
   (setq image-transform-scale 1.0)
   (when (or image-transform-resize
             (/= image-transform-rotation 0.0))
@@ -1302,41 +1311,32 @@ compiled with ImageMagick support."
             (list :rotation image-transform-rotation))))))
 
 (defun image-transform-set-scale (scale)
-  "Prompt for a number, and resize the current image by that amount.
-This command has no effect unless Emacs is compiled with
-ImageMagick support."
+  "Prompt for a number, and resize the current image by that amount."
   (interactive "nScale: ")
   (setq image-transform-resize scale)
   (image-toggle-display-image))
 
 (defun image-transform-fit-to-height ()
-  "Fit the current image to the height of the current window.
-This command has no effect unless Emacs is compiled with
-ImageMagick support."
+  "Fit the current image to the height of the current window."
   (interactive)
   (setq image-transform-resize 'fit-height)
   (image-toggle-display-image))
 
 (defun image-transform-fit-to-width ()
-  "Fit the current image to the width of the current window.
-This command has no effect unless Emacs is compiled with
-ImageMagick support."
+  "Fit the current image to the width of the current window."
   (interactive)
   (setq image-transform-resize 'fit-width)
   (image-toggle-display-image))
 
 (defun image-transform-set-rotation (rotation)
   "Prompt for an angle ROTATION, and rotate the image by that amount.
-ROTATION should be in degrees.  This command has no effect unless
-Emacs is compiled with ImageMagick support."
+ROTATION should be in degrees."
   (interactive "nRotation angle (in degrees): ")
   (setq image-transform-rotation (float (mod rotation 360)))
   (image-toggle-display-image))
 
 (defun image-transform-reset ()
-  "Display the current image with the default size and rotation.
-This command has no effect unless Emacs is compiled with
-ImageMagick support."
+  "Display the current image with the default size and rotation."
   (interactive)
   (setq image-transform-resize nil
         image-transform-rotation 0.0
diff --git a/lisp/image/exif.el b/lisp/image/exif.el
index 065456dc318..6aeb52c726d 100644
--- a/lisp/image/exif.el
+++ b/lisp/image/exif.el
@@ -95,7 +95,7 @@ mirrored or not.")
   "Parse FILE (a JPEG file) and return the Exif data, if any.
 The return value is a list of Exif items.
 
-If the data is invalid, an `exif-error' is signalled."
+If the data is invalid, an `exif-error' is signaled."
   (with-temp-buffer
     (set-buffer-multibyte nil)
     (insert-file-contents-literally file)
@@ -105,7 +105,7 @@ If the data is invalid, an `exif-error' is signalled."
   "Parse BUFFER (which should be a JPEG file) and return the Exif data, if any.
 The return value is a list of Exif items.
 
-If the data is invalid, an `exif-error' is signalled."
+If the data is invalid, an `exif-error' is signaled."
   (setq buffer (or buffer (current-buffer)))
   (with-current-buffer buffer
     (if enable-multibyte-characters
diff --git a/lisp/international/mule-util.el b/lisp/international/mule-util.el
index caa5747817c..5cc10b1315a 100644
--- a/lisp/international/mule-util.el
+++ b/lisp/international/mule-util.el
@@ -75,7 +75,7 @@ unless the display width of STR is equal to or less than the display
 width of ELLIPSIS.  If it is non-nil and not a string, then ELLIPSIS
 defaults to `truncate-string-ellipsis'.
 
-If ELLIPSIS-TEXT-PROPERTY in non-nil, a too-long string will not
+If ELLIPSIS-TEXT-PROPERTY is non-nil, a too-long string will not
 be truncated, but instead the elided parts will be covered by a
 `display' text property showing the ellipsis."
   (or start-column
diff --git a/lisp/json.el b/lisp/json.el
index 055f3f5be11..6f3b791ed17 100644
--- a/lisp/json.el
+++ b/lisp/json.el
@@ -736,7 +736,7 @@ you will get the following structure returned:
 
 OBJECT should have a structure like one returned by `json-read'.
 If an error is detected during encoding, an error based on
-`json-error' is signalled."
+`json-error' is signaled."
   (cond ((memq object (list t json-null json-false))
          (json-encode-keyword object))
         ((stringp object)      (json-encode-string object))
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 6090e3f74ed..d2c3f9045e5 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -163,8 +163,8 @@ perform completion, no matter what ACTION is.
 
 If ACTION is `metadata' or a list where the first element is
 `boundaries', return nil.  If ACTION is nil, this function works
-like `try-completion'; if it's t, this function works like
-`all-completion'; and any other values makes it work like
+like `try-completion'; if it is t, this function works like
+`all-completion'; and any other value makes it work like
 `test-completion'."
   (cond
    ((functionp collection) (funcall collection string predicate action))
diff --git a/lisp/obsolete/cl.el b/lisp/obsolete/cl.el
index 1da4289b695..20bffffd781 100644
--- a/lisp/obsolete/cl.el
+++ b/lisp/obsolete/cl.el
@@ -509,7 +509,7 @@ This method shows how to handle `setf's to places of the form
 ARGLIST, as if NAME were going to be expanded as a macro, then
 the BODY forms are executed and must return a list of five elements:
 a temporary-variables list, a value-forms list, a store-variables list
-\(of length one), a store-form, and an access- form.
+\(of length one), a store-form, and an access-form.
 
 See `gv-define-expander', and `gv-define-setter' for better and
 simpler ways to define setf-methods."
diff --git a/lisp/sort.el b/lisp/sort.el
index e4ff2afb3d7..de0e1b9519d 100644
--- a/lisp/sort.el
+++ b/lisp/sort.el
@@ -198,7 +198,8 @@ as start and end positions), and with `string<' otherwise."
 
 ;;;###autoload
 (defun sort-lines (reverse beg end)
-  "Sort lines in region alphabetically; argument means descending order.
+  "Sort lines in region alphabetically; REVERSE non-nil means descending order.
+Interactively, REVERSE is the prefix argument, and BEG and END are the region.
 Called from a program, there are three arguments:
 REVERSE (non-nil means reverse order), BEG and END (region to sort).
 The variable `sort-fold-case' determines whether alphabetic case affects
diff --git a/lisp/startup.el b/lisp/startup.el
index 5af264e3ef7..bff10003f84 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -352,11 +352,11 @@ Setting `init-file-user' does not prevent Emacs from loading
 
 (defcustom site-run-file (purecopy "site-start")
   "File containing site-wide run-time initializations.
-This file is loaded at run-time before `~/.emacs'.  It contains inits
-that need to be in place for the entire site, but which, due to their
-higher incidence of change, don't make sense to put into Emacs's
+This file is loaded at run-time before `user-init-file'.  It contains
+inits that need to be in place for the entire site, but which, due to
+their higher incidence of change, don't make sense to put into Emacs's
 dump file.  Thus, the run-time load order is: 1. file described in
-this variable, if non-nil; 2. `~/.emacs'; 3. `default.el'.
+this variable, if non-nil; 2. `user-init-file'; 3. `default.el'.
 
 Don't use the `site-start.el' file for things some users may not like.
 Put them in `default.el' instead, so that users can more easily
diff --git a/lisp/subr.el b/lisp/subr.el
index f7445d8c25e..c8913145a18 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -385,7 +385,7 @@ entry to the debugger, even when `debug-on-error' is non-nil.
 This can be overridden by `debug-ignored-errors'.
 
 To signal with MESSAGE without interpreting format characters
-like `%', `\\=`' and `\\='', use (error \"%s\" MESSAGE).
+like `%', `\\=`' and `\\='', use (user-error \"%s\" MESSAGE).
 In Emacs, the convention is that error messages start with a capital
 letter but *do not* end with a period.  Please follow this convention
 for the sake of consistency."
@@ -3314,7 +3314,7 @@ alternatives."
 
 (defun function-get (f prop &optional autoload)
   "Return the value of property PROP of function F.
-If AUTOLOAD is non-nil and F is autoloaded, try to autoload it
+If AUTOLOAD is non-nil and F is autoloaded, try to load it
 in the hope that it will set PROP.  If AUTOLOAD is `macro', do it only
 if it's an autoloaded macro."
   (let ((val nil))
@@ -5021,7 +5021,7 @@ The properties used on SYMBOL are `composefunc', `sendfunc',
 (defun backtrace-frames (&optional base)
   "Collect all frames of current backtrace into a list.
 If non-nil, BASE should be a function, and frames before its
-nearest activation frames are discarded."
+nearest activation frame are discarded."
   (let ((frames nil))
     (mapbacktrace (lambda (&rest frame) (push frame frames))
                   (or base 'backtrace-frames))
diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el
index a9fbd2f04cb..65f61644b6d 100644
--- a/lisp/textmodes/ispell.el
+++ b/lisp/textmodes/ispell.el
@@ -800,8 +800,8 @@ Otherwise returns the library directory name, if that is defined."
 
 (defun ispell-create-debug-buffer (&optional append)
   "Create an ispell debug buffer for debugging output.
-If APPEND is non-nil, append the info to previous buffer if exists,
-otherwise is reset.  Returns name of ispell debug buffer.
+If APPEND is non-nil, add output to the old buffer if it exists,
+otherwise the buffer is erased first.  Returns the debug buffer.
 See `ispell-buffer-with-debug' for an example of use."
   (let ((ispell-debug-buffer (get-buffer-create "*ispell-debug*")))
     (with-current-buffer ispell-debug-buffer
@@ -812,7 +812,7 @@ See `ispell-buffer-with-debug' for an example of use."
     ispell-debug-buffer))
 
 (defsubst ispell-print-if-debug (format &rest args)
-  "Print message using FORMAT and ARGS to `ispell-debug-buffer' buffer if enabled."
+  "Print message using FORMAT and ARGS to `ispell-debug-buffer' if enabled."
   (if (boundp 'ispell-debug-buffer)
       (with-current-buffer ispell-debug-buffer
         (goto-char (point-max))
@@ -3618,8 +3618,8 @@ Returns the sum SHIFT due to changes in word replacements."
 
 ;;;###autoload
 (defun ispell-buffer-with-debug (&optional append)
-  "`ispell-buffer' with some output sent to `ispell-debug-buffer' buffer.
-If APPEND is non-n il, append the info to previous buffer if exists."
+  "`ispell-buffer' with some output sent to `ispell-debug-buffer'.
+If APPEND is non-nil, don't erase previous debugging output."
   (interactive)
   (let ((ispell-debug-buffer (ispell-create-debug-buffer append)))
     (ispell-buffer)))