(checkdoc-this-string-valid-engine):

Improve messages for capitalization of arg names,
for flag variables, for t and nil, for imperatives.
Call them imperatives rather than infinitives sans "to".
(checkdoc-common-verbs-wrong-voice): Add "moves".
(checkdoc-message-text-engine): Improve messages for y-or-n-p.

(checkdoc-file-comments-engine):
Don't convert comments from 3-semicolon to 2-semicolon.
That is a matter of style.
(checkdoc-triple-semi-comment-check-flag): Variable deleted.
(checkdoc-comments): Don't bind that variable.

1 files changed, 17 insertions, 65 deletions

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 102e6850a1e..62d4566124d 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -233,19 +233,6 @@ it indicates that a modifying clause follows."
   :group 'checkdoc
   :type 'boolean)
 
-(defcustom checkdoc-triple-semi-comment-check-flag t
-  "*Non-nil means to check for multiple adjacent occurrences of ;;; comments.
-According to the style of Emacs code in the Lisp libraries, a block
-comment can look like this:
-;;; Title
-;;  text
-;;  text
-But when inside a function, code can be commented out using the ;;;
-construct for all lines.  When this variable is nil, the ;;; construct
-is ignored regardless of its location in the code."
-  :group 'checkdoc
-  :type 'boolean)
-
 (defcustom checkdoc-spellcheck-documentation-flag nil
   "*Non-nil means run Ispell on text based on value.
 This is automatically set to nil if Ispell does not exist on your
@@ -382,6 +369,7 @@ This should be set in an Emacs Lisp file's local variables."
     ("makes" . "make")
     ("marks" . "mark")
     ("matches" . "match")
+    ("moves" . "move")
     ("notifies" . "notify")
     ("offers" . "offer")
     ("parses" . "parse")
@@ -924,9 +912,6 @@ if there is one."
           (member checkdoc-spellcheck-documentation-flag
                   '(buffer t)))
          (checkdoc-autofix-flag (if take-notes 'never checkdoc-autofix-flag))
-         ;; This is just irritating when taking notes.
-         (checkdoc-triple-semi-comment-check-flag
-          (if take-notes nil checkdoc-triple-semi-comment-check-flag))
          (e (checkdoc-file-comments-engine))
         (checkdoc-generate-compile-warnings-flag
          (or take-notes checkdoc-generate-compile-warnings-flag)))
@@ -1623,7 +1608,7 @@ function,command,variable,option or symbol." ms1))))))
              (if (and (string-match "-flag$" (car fp))
                       (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
                  (checkdoc-create-error
-                  "Flag variable doc strings should start: Non-nil means"
+                  "Flag variable doc strings should usually start: Non-nil means"
                   s (marker-position e) t))
              ;; If the doc string starts with "Non-nil means"
              (if (and (looking-at "\"\\*?Non-nil\\s-+means\\s-+")
@@ -1638,7 +1623,7 @@ function,command,variable,option or symbol." ms1))))))
                         (concat "\\<" (regexp-quote (car fp)) "\\>")
                         (concat (car fp) "-flag")))
                    (checkdoc-create-error
-                    "Flag variables should end in `-flag'" s
+                    "Flag variable names should normally end in `-flag'" s
                     (marker-position e))))
              ;; Done with variables
              ))
@@ -1689,7 +1674,7 @@ function,command,variable,option or symbol." ms1))))))
                              (if (checkdoc-autofix-ask-replace
                                   (match-beginning 1) (match-end 1)
                                   (format
-                                   "Argument `%s' should appear as `%s'.  Fix? "
+                                   "If this is the argument `%s', it should appear as %s.  Fix? "
                                    (car args) (upcase (car args)))
                                   (upcase (car args)) t)
                                  (setq found (match-beginning 1))))))
@@ -1715,7 +1700,7 @@ function,command,variable,option or symbol." ms1))))))
                          nil)
                      (checkdoc-create-error
                       (format
-                       "Argument `%s' should appear (as `%s') in the doc string"
+                       "Argument `%s' should appear (as %s) in the doc string"
                        (car args) (upcase (car args)))
                       s (marker-position e)))
                  (if (or (and order (eq order 'yes))
@@ -1725,8 +1710,8 @@ function,command,variable,option or symbol." ms1))))))
                           "Arguments occur in the doc string out of order"
                           s (marker-position e) t)))))
              ;; * For consistency, phrase the verb in the first sentence of a
-             ;;   documentation string for functions as an infinitive with
-             ;;   "to" omitted.  For instance, use `Return the cons of A and
+             ;;   documentation string for functions as an imperative.
+             ;;   For instance, use `Return the cons of A and
              ;;   B.' in preference to `Returns the cons of A and B.'
              ;;   Usually it looks good to do likewise for the rest of the
              ;;   first paragraph.  Subsequent paragraphs usually look better
@@ -1762,15 +1747,15 @@ function,command,variable,option or symbol." ms1))))))
                                             (cdr rs)))))
                         (if (checkdoc-autofix-ask-replace
                              (match-beginning 1) (match-end 1)
-                             (format "Use the infinitive for `%s'.  \
-Replace with `%s'? " original replace)
+                             (format "Use the imperative for \"%s\".  \
+Replace with \"%s\"? " original replace)
                              replace t)
                             (setq rs nil)))
                       (if rs
                           ;; there was a match, but no replace
                           (checkdoc-create-error
                            (format
-                            "Infinitive `%s' should be replaced with `%s'"
+                            "Probably \"%s\" should be imperative \"%s\""
                             original replace)
                            (match-beginning 1) (match-end 1))))))
              ;; Done with functions
@@ -1823,7 +1808,7 @@ Replace with `%s'? " original replace)
                 (match-string 2) t)
                nil
              (checkdoc-create-error
-              "Symbols t and nil should not appear in `quotes'"
+              "Symbols t and nil should not appear in `...' quotes"
               (match-beginning 1) (match-end 1)))))
      ;; Here is some basic sentence formatting
      (checkdoc-sentencespace-region-engine (point) e)
@@ -2315,39 +2300,6 @@ Code:, and others referenced in the style guide."
                  (1- (point-max)) (point-max)))))
         err))
       ;; The below checks will not return errors if the user says NO
-      
-      ;; Ok, now let's look for multiple occurrences of ;;;, and offer
-      ;; to remove the extra ";" if applicable.  This pre-supposes
-      ;; that the user has semiautomatic fixing on to be useful.
-      
-      ;; In the info node (elisp)Library Headers a header is three ;
-      ;; (the header) followed by text of only two ;
-      ;; In (elisp)Comment Tips, however it says this:
-      ;; * Another use for triple-semicolon comments is for commenting out
-      ;;   lines within a function.  We use triple-semicolons for this
-      ;;   precisely so that they remain at the left margin.
-      (let ((msg nil))
-        (goto-char (point-min))
-        (while (and checkdoc-triple-semi-comment-check-flag
-                    (not msg) (re-search-forward "^;;;[^;]" nil t))
-          ;; We found a triple, let's check all following lines.
-          (if (not (bolp)) (progn (beginning-of-line) (forward-line 1)))
-          (let ((complex-replace t)
-                (dont-replace nil))
-            (while (looking-at ";;\\(;\\)[^;#]")
-              (if (and (not dont-replace)
-                       (checkdoc-outside-major-sexp) ;in code is ok.
-                       (checkdoc-autofix-ask-replace
-                        (match-beginning 1) (match-end 1)
-                        "Multiple occurrences of ;;; found.  Use ;; instead? "
-                        "" complex-replace))
-                  ;; Learn that, yea, the user did want to do this a
-                  ;; whole bunch of times.
-                  (setq complex-replace nil)
-                ;; In this case, skip all this crap
-                (setq dont-replace t))
-              (beginning-of-line)
-              (forward-line 1)))))
 
       ;; Let's spellcheck the commentary section.  This is the only
       ;; section that is easy to pick out, and it is also the most
@@ -2496,22 +2448,22 @@ Argument TYPE specifies the type of question, such as `error or `y-or-n-p."
                ;; If we see a ?, then replace with "? ".
                (if (checkdoc-autofix-ask-replace
                     (match-beginning 0) (match-end 0)
-                    "y-or-n-p text should end with \"? \".  Fix? "
+                    "`y-or-n-p' argument should end with \"? \".  Fix? "
                     "? " t)
                    nil
                  (checkdoc-create-error
-                  "y-or-n-p text should end with \"? \""
+                  "`y-or-n-p' argument should end with \"? \""
                   (match-beginning 0) (match-end 0)))
              (if (save-excursion (forward-sexp 1)
                                  (forward-char -2)
                                  (looking-at " "))
                  (if (checkdoc-autofix-ask-replace
                       (match-beginning 0) (match-end 0)
-                      "y-or-n-p text should end with \"? \".  Fix? "
+                      "`y-or-n-p' argument should end with \"? \".  Fix? "
                       "? " t)
                      nil
                    (checkdoc-create-error
-                    "y-or-n-p text should end with \"? \""
+                    "`y-or-n-p' argument should end with \"? \""
                     (match-beginning 0) (match-end 0)))
                (if (and ;; if this isn't true, we have a problem.
                     (save-excursion (forward-sexp 1)
@@ -2519,11 +2471,11 @@ Argument TYPE specifies the type of question, such as `error or `y-or-n-p."
                                     (looking-at "\""))
                     (checkdoc-autofix-ask-replace
                      (match-beginning 0) (match-end 0)
-                     "y-or-n-p text should end with \"? \".  Fix? "
+                     "`y-or-n-p' argument should end with \"? \".  Fix? "
                      "? \"" t))
                    nil
                  (checkdoc-create-error
-                  "y-or-n-p text should end with \"? \""
+                  "`y-or-n-p' argument should end with \"? \""
                   (match-beginning 0) (match-end 0)))))))
      ;; Now, let's just run the spell checker on this guy.
      (checkdoc-ispell-docstring-engine (save-excursion (forward-sexp 1)