Vale styles for the comments in code: the conventions of Go doc comments, Javadoc, and KDoc, and a core that applies in any language: owned TODOs, no commented-out code.
Vale reads the comments out of source files and lints only those, so the
rules see // Add returns the sum and never the code beside it. Works on
every language Vale extracts comments from.
Requires Vale 3.23.0 or later.
StylesPath = styles
Packages = https://github.com/jdkato/comments/releases/latest/download/Comments.zip
[*.go]
BasedOnStyles = Comments, GoDoc
[*.java]
BasedOnStyles = Comments, Javadoc
[*.kt]
BasedOnStyles = Comments, KDoc
[*.{py,rs,ts,js}]
BasedOnStyles = Comments$ vale sync| Style | What it checks |
|---|---|
Comments |
TODO without an owner, FIXME and XXX and HACK, and commented-out code. Any language. |
GoDoc |
A doc comment that is a sentence and ends with one, starts with the name it documents rather than "This function", a Package name comment, and a Deprecated: paragraph the tools can read. |
Javadoc |
The first sentence ends with a period, "This method" openers, a @param or @return with nothing after it, and tags in the order @param, @return, @throws. |
KDoc |
The same as Javadoc, for Kotlin. |
Every rule file starts with a comment explaining what it checks and links to the convention it comes from. Alerts land on the comment, at the word.
A rule reads one comment at a time and not the code it documents, so it
can't tell that Add is the name a comment should open with, or that a
@param names a parameter the method has. Those stay with the compiler's
own tools; this package covers what they don't.
./test.sh runs each rule's own cases with vale test --coverage, then
checks one file per language in fixtures/ against the golden files in
testdata/ and requires the rewrites in fixtures/clean/ to pass clean.
./test.sh -u rewrites the golden files.
