Mercurial > emacs
changeset 26615:1d769c66f407
(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.
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Fri, 26 Nov 1999 17:33:36 +0000 |
| parents | 2616986242eb |
| children | 615e184ede1b |
| files | lisp/emacs-lisp/checkdoc.el |
| diffstat | 1 files changed, 17 insertions(+), 65 deletions(-) [+] |
line wrap: on
line diff
--- a/lisp/emacs-lisp/checkdoc.el Fri Nov 26 17:33:31 1999 +0000 +++ b/lisp/emacs-lisp/checkdoc.el Fri Nov 26 17:33:36 1999 +0000 @@ -233,19 +233,6 @@ :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 @@ ("makes" . "make") ("marks" . "mark") ("matches" . "match") + ("moves" . "move") ("notifies" . "notify") ("offers" . "offer") ("parses" . "parse") @@ -924,9 +912,6 @@ (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 @@ (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 @@ (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 @@ (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 @@ 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 @@ "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 @@ (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 @@ (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 @@ (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 @@ ;; 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 @@ (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)