Commit 995e028a authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(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.
parent 88a26eb4
...@@ -233,19 +233,6 @@ it indicates that a modifying clause follows." ...@@ -233,19 +233,6 @@ it indicates that a modifying clause follows."
:group 'checkdoc :group 'checkdoc
:type 'boolean) :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 (defcustom checkdoc-spellcheck-documentation-flag nil
"*Non-nil means run Ispell on text based on value. "*Non-nil means run Ispell on text based on value.
This is automatically set to nil if Ispell does not exist on your 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." ...@@ -382,6 +369,7 @@ This should be set in an Emacs Lisp file's local variables."
("makes" . "make") ("makes" . "make")
("marks" . "mark") ("marks" . "mark")
("matches" . "match") ("matches" . "match")
("moves" . "move")
("notifies" . "notify") ("notifies" . "notify")
("offers" . "offer") ("offers" . "offer")
("parses" . "parse") ("parses" . "parse")
...@@ -924,9 +912,6 @@ if there is one." ...@@ -924,9 +912,6 @@ if there is one."
(member checkdoc-spellcheck-documentation-flag (member checkdoc-spellcheck-documentation-flag
'(buffer t))) '(buffer t)))
(checkdoc-autofix-flag (if take-notes 'never checkdoc-autofix-flag)) (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)) (e (checkdoc-file-comments-engine))
(checkdoc-generate-compile-warnings-flag (checkdoc-generate-compile-warnings-flag
(or take-notes checkdoc-generate-compile-warnings-flag))) (or take-notes checkdoc-generate-compile-warnings-flag)))
...@@ -1623,7 +1608,7 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1623,7 +1608,7 @@ function,command,variable,option or symbol." ms1))))))
(if (and (string-match "-flag$" (car fp)) (if (and (string-match "-flag$" (car fp))
(not (looking-at "\"\\*?Non-nil\\s-+means\\s-+"))) (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
(checkdoc-create-error (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)) s (marker-position e) t))
;; If the doc string starts with "Non-nil means" ;; If the doc string starts with "Non-nil means"
(if (and (looking-at "\"\\*?Non-nil\\s-+means\\s-+") (if (and (looking-at "\"\\*?Non-nil\\s-+means\\s-+")
...@@ -1638,7 +1623,7 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1638,7 +1623,7 @@ function,command,variable,option or symbol." ms1))))))
(concat "\\<" (regexp-quote (car fp)) "\\>") (concat "\\<" (regexp-quote (car fp)) "\\>")
(concat (car fp) "-flag"))) (concat (car fp) "-flag")))
(checkdoc-create-error (checkdoc-create-error
"Flag variables should end in `-flag'" s "Flag variable names should normally end in `-flag'" s
(marker-position e)))) (marker-position e))))
;; Done with variables ;; Done with variables
)) ))
...@@ -1689,7 +1674,7 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1689,7 +1674,7 @@ function,command,variable,option or symbol." ms1))))))
(if (checkdoc-autofix-ask-replace (if (checkdoc-autofix-ask-replace
(match-beginning 1) (match-end 1) (match-beginning 1) (match-end 1)
(format (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))) (car args) (upcase (car args)))
(upcase (car args)) t) (upcase (car args)) t)
(setq found (match-beginning 1)))))) (setq found (match-beginning 1))))))
...@@ -1715,7 +1700,7 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1715,7 +1700,7 @@ function,command,variable,option or symbol." ms1))))))
nil) nil)
(checkdoc-create-error (checkdoc-create-error
(format (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))) (car args) (upcase (car args)))
s (marker-position e))) s (marker-position e)))
(if (or (and order (eq order 'yes)) (if (or (and order (eq order 'yes))
...@@ -1725,8 +1710,8 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1725,8 +1710,8 @@ function,command,variable,option or symbol." ms1))))))
"Arguments occur in the doc string out of order" "Arguments occur in the doc string out of order"
s (marker-position e) t))))) s (marker-position e) t)))))
;; * For consistency, phrase the verb in the first sentence of a ;; * For consistency, phrase the verb in the first sentence of a
;; documentation string for functions as an infinitive with ;; documentation string for functions as an imperative.
;; "to" omitted. For instance, use `Return the cons of A and ;; For instance, use `Return the cons of A and
;; B.' in preference to `Returns the cons of A and B.' ;; B.' in preference to `Returns the cons of A and B.'
;; Usually it looks good to do likewise for the rest of the ;; Usually it looks good to do likewise for the rest of the
;; first paragraph. Subsequent paragraphs usually look better ;; first paragraph. Subsequent paragraphs usually look better
...@@ -1762,15 +1747,15 @@ function,command,variable,option or symbol." ms1)))))) ...@@ -1762,15 +1747,15 @@ function,command,variable,option or symbol." ms1))))))
(cdr rs))))) (cdr rs)))))
(if (checkdoc-autofix-ask-replace (if (checkdoc-autofix-ask-replace
(match-beginning 1) (match-end 1) (match-beginning 1) (match-end 1)
(format "Use the infinitive for `%s'. \ (format "Use the imperative for \"%s\". \
Replace with `%s'? " original replace) Replace with \"%s\"? " original replace)
replace t) replace t)
(setq rs nil))) (setq rs nil)))
(if rs (if rs
;; there was a match, but no replace ;; there was a match, but no replace
(checkdoc-create-error (checkdoc-create-error
(format (format
"Infinitive `%s' should be replaced with `%s'" "Probably \"%s\" should be imperative \"%s\""
original replace) original replace)
(match-beginning 1) (match-end 1)))))) (match-beginning 1) (match-end 1))))))
;; Done with functions ;; Done with functions
...@@ -1823,7 +1808,7 @@ Replace with `%s'? " original replace) ...@@ -1823,7 +1808,7 @@ Replace with `%s'? " original replace)
(match-string 2) t) (match-string 2) t)
nil nil
(checkdoc-create-error (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))))) (match-beginning 1) (match-end 1)))))
;; Here is some basic sentence formatting ;; Here is some basic sentence formatting
(checkdoc-sentencespace-region-engine (point) e) (checkdoc-sentencespace-region-engine (point) e)
...@@ -2315,39 +2300,6 @@ Code:, and others referenced in the style guide." ...@@ -2315,39 +2300,6 @@ Code:, and others referenced in the style guide."
(1- (point-max)) (point-max))))) (1- (point-max)) (point-max)))))
err)) err))
;; The below checks will not return errors if the user says NO ;; 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 ;; Let's spellcheck the commentary section. This is the only
;; section that is easy to pick out, and it is also the most ;; 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." ...@@ -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 we see a ?, then replace with "? ".
(if (checkdoc-autofix-ask-replace (if (checkdoc-autofix-ask-replace
(match-beginning 0) (match-end 0) (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) "? " t)
nil nil
(checkdoc-create-error (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))) (match-beginning 0) (match-end 0)))
(if (save-excursion (forward-sexp 1) (if (save-excursion (forward-sexp 1)
(forward-char -2) (forward-char -2)
(looking-at " ")) (looking-at " "))
(if (checkdoc-autofix-ask-replace (if (checkdoc-autofix-ask-replace
(match-beginning 0) (match-end 0) (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) "? " t)
nil nil
(checkdoc-create-error (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))) (match-beginning 0) (match-end 0)))
(if (and ;; if this isn't true, we have a problem. (if (and ;; if this isn't true, we have a problem.
(save-excursion (forward-sexp 1) (save-excursion (forward-sexp 1)
...@@ -2519,11 +2471,11 @@ Argument TYPE specifies the type of question, such as `error or `y-or-n-p." ...@@ -2519,11 +2471,11 @@ Argument TYPE specifies the type of question, such as `error or `y-or-n-p."
(looking-at "\"")) (looking-at "\""))
(checkdoc-autofix-ask-replace (checkdoc-autofix-ask-replace
(match-beginning 0) (match-end 0) (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)) "? \"" t))
nil nil
(checkdoc-create-error (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))))))) (match-beginning 0) (match-end 0)))))))
;; Now, let's just run the spell checker on this guy. ;; Now, let's just run the spell checker on this guy.
(checkdoc-ispell-docstring-engine (save-excursion (forward-sexp 1) (checkdoc-ispell-docstring-engine (save-excursion (forward-sexp 1)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment