Since Checkstyle 3.2
Validates Javadoc comments to help ensure they are well formed.
The following checks are performed:
{@inheritDoc}
tag are exempt from this
requirement.
@param
and @return
.
These checks were patterned after the checks made by the DocCheck doclet available from Sun. Note: Original Sun's DocCheck tool does not exist anymore.
name | description | type | default value | since |
---|---|---|---|---|
scope | Specify the visibility scope where Javadoc comments are checked. | Scope | private |
3.2 |
excludeScope | Specify the visibility scope where Javadoc comments are not checked. | Scope | null |
3.4 |
checkFirstSentence | Control whether to check the first sentence for proper end of sentence. | boolean | true |
3.2 |
endOfSentenceFormat | Specify the format for matching the end of a sentence. | Pattern | "([.?!][ \t\n\r\f<])|([.?!]$)" |
5.0 |
checkEmptyJavadoc | Control whether to check if the Javadoc is missing a describing text. | boolean | false |
3.4 |
checkHtml | Control whether to check for incomplete HTML tags. | boolean | true |
3.2 |
tokens | tokens to check | subset of tokens ANNOTATION_DEF , ANNOTATION_FIELD_DEF , CLASS_DEF , CTOR_DEF , ENUM_CONSTANT_DEF , ENUM_DEF , INTERFACE_DEF , METHOD_DEF , PACKAGE_DEF , VARIABLE_DEF , RECORD_DEF , COMPACT_CTOR_DEF . | ANNOTATION_DEF , ANNOTATION_FIELD_DEF , CLASS_DEF , CTOR_DEF , ENUM_CONSTANT_DEF , ENUM_DEF , INTERFACE_DEF , METHOD_DEF , PACKAGE_DEF , VARIABLE_DEF , RECORD_DEF , COMPACT_CTOR_DEF . | 3.2 |
To configure the default check:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"/> </module> </module>
Example:
public class Test { /** * Some description here. // OK */ private void methodWithValidCommentStyle() {} /** * Some description here // violation, the sentence must end with a proper punctuation */ private void methodWithInvalidCommentStyle() {} }
To configure the check for public
scope:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"> <property name="scope" value="public"/> </module> </module> </module>
Example:
public class Test { /** * Some description here // violation, the sentence must end with a proper punctuation */ public void test1() {} /** * Some description here // OK */ private void test2() {} }
To configure the check for javadoc which is in private
, but not in
package
scope:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"> <property name="scope" value="private"/> <property name="excludeScope" value="package"/> </module> </module> </module>
Example:
public class Test { /** * Some description here // violation, the sentence must end with a proper punctuation */ private void test1() {} /** * Some description here // OK */ void test2() {} }
To configure the check to turn off first sentence checking:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"> <property name="checkFirstSentence" value="false"/> </module> </module> </module>
Example:
public class Test { /** * Some description here // OK * Second line of description // violation, the sentence must end with a proper punctuation */ private void test1() {} }
To configure the check to turn off validation of incomplete html tags:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"> <property name="checkHtml" value="false"/> </module> </module> </module>
Example:
public class Test { /** * Some description here // violation, the sentence must end with a proper punctuation * <p // OK */ private void test1() {} }
To configure the check for only class definitions:
<module name="Checker"> <module name="TreeWalker"> <module name="JavadocStyle"> <property name="tokens" value="CLASS_DEF"/> </module> </module> </module>
Example:
/** * Some description here // violation, the sentence must end with a proper punctuation */ public class Test { /** * Some description here // OK */ private void test1() {} }
All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.
com.puppycrawl.tools.checkstyle.checks.javadoc