(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.

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 102e6850a1ef30a365936477551f1cf44b0ec340..62d4566124d0890b85286db371e5ce2b50d87122 100644 (file)
--- 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)