procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
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.
This commit is contained in:
Richard M. Stallman 1999-11-26 17:33:36 +00:00
parent 88a26eb413
commit 995e028a96
1 changed files with 17 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

82
lisp/emacs-lisp/checkdoc.el
View file

@ -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)