Content

AtclauseOrder

Description

Checks the order of at-clauses.

Properties

name description type default value
target allows to specify targets to check at-clauses. subset of tokens CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF. CLASS_DEF, INTERFACE_DEF, ENUM_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF.
tagOrder allows to specify the order by tags. String @author, @version, @param, @return, @throws, @exception, @see, @since, @serial, @serialField, @serialData, @deprecated

Examples

Default configuration 

<module name="AtclauseOrder">
    <property name="tagOrder" value="@author, @version, @param,
    @return, @throws, @exception, @see, @since, @serial,
    @serialField, @serialData, @deprecated"/>
    <property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
    METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocMethod

Description

Checks the Javadoc of a method or constructor. By default, does not check for unused throws. To allow documented java.lang.RuntimeExceptions that are not declared, set property allowUndeclaredRTE to true. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to a different scope.

Error messages about parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags. Error messages about exceptions which are declared to be thrown, but for which no throws tag is present can be suppressed by defining property allowMissingThrowsTags. Error messages about methods which return non-void but for which no return tag is present can be suppressed by defining property allowMissingReturnTag.

Javadoc is not required on a method that is tagged with the @Override annotation. However under Java 5 it is not possible to mark a method required for an interface (this was corrected under Java 6). Hence Checkstyle supports using the convention of using a single {@inheritDoc} tag instead of all the other tags.

Note that only inheritable items will allow the {@inheritDoc} tag to be used in place of comments. Static methods at all visibilities, private non-static methods and constructors are not inheritable.

For example, if the following method is implementing a method required by an interface, then the Javadoc could be done as: 

/** {@inheritDoc} */
public int checkReturnTag(final int aTagIndex,
                          JavadocTag[] aTags,
                          int aLineNo)

The classpath may need to be configured to locate the class information. The classpath configuration is dependent on the mechanism used to invoke Checkstyle.

Properties

name description type default value
minLineCount Minimal amount of lines in method to demand documentation presence. Integer -1
allowedAnnotations List of annotations that could allow missed documentation. list of strings Override
validateThrows Allows validating throws tags. boolean false
scope visibility scope where Javadoc comments are checked scope private
excludeScope visibility scope where Javadoc comments are not checked scope null
allowUndeclaredRTE whether to allow documented exceptions that are not declared if they are a subclass of java.lang.RuntimeException boolean false
allowThrowsTagsForSubclasses whether to allow documented exceptions that are subclass of one of declared exception. boolean false
allowMissingParamTags whether to ignore errors when a method has parameters but does not have matching param tags in the javadoc. boolean false
allowMissingThrowsTags whether to ignore errors when a method declares that it throws exceptions but does have matching throws tags in the javadoc. boolean false
allowMissingReturnTag whether to ignore errors when a method returns non-void type does have a return tag in the javadoc. boolean false
allowMissingJavadoc whether to ignore errors when a method javadoc is missed. boolean false
allowMissingPropertyJavadoc Whether to allow missing Javadoc on accessor methods for properties (setters and getters). The setter and getter methods must match exactly the structures below. 
public void setNumber(final int number)
{
    mNumber = number;
}

public int getNumber()
{
    return mNumber;
}

public boolean isSomething()
{
    return false;
}
boolean false
logLoadErrors This check may need to load exception classes mentioned in the @throws tag to check whether they are RuntimeExceptions. If loading the class fails, this property allows to control checkstyle's error handling. If set to false a classpath configuration problem is assumed and the TreeWalker stops operating on the class completely. If set to true (the default) , checkstyle assumes a typo or refactoring problem in the javadoc and logs the problem in the normal checkstyle report (potentially masking a configuration error). boolean true
suppressLoadErrors When logLoadErrors is set to true, the TreeWalker completely processes a class and displays any problems with loading exceptions as checkstyle violations. When this property is set to true, the violations generated when logLoadErrors is set true are suppressed from being reported as violations in the checkstyle report. boolean false
ignoreMethodNamesRegex ignore method whose names are matching specified regex regular expression null (tag not required)
tokens tokens to check subset of tokens METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF. METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF.

Examples

To configure the default check: 

<module name="JavadocMethod"/>

To configure the check for public scope and to allow documentation of undeclared RuntimeExceptions: 

<module name="JavadocMethod">
   <property name="scope" value="public"/>
   <property name="allowUndeclaredRTE" value="true"/>
</module>

To configure the check for for public scope, to allow documentation of undeclared RuntimeExceptions, while ignoring any missing param tags is: 

<module name="JavadocMethod">
  <property name="scope" value="public"/>
  <property name="allowUndeclaredRTE" value="true"/>
  <property name="allowMissingParamTags" value="true"/>
</module>

To configure the check for methods which are in private , but not in protected scope: 

<module name="JavadocMethod">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
</module>

To configure the check for ignoring methods named foo(),foo1(),foo2(), etc.: 

<module name="JavadocMethod">
   <property name="ignoreMethodNamesRegex" value="^foo.*$"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocPackage

Description

Checks that each Java package has a Javadoc file used for commenting. By default it only allows a package-info.java file, but can be configured to allow a package.html file.

An error will be reported if both files exist as this is not allowed by the Javadoc tool.

Properties

name description type default value
allowLegacy If set then allow the use of a package.html file. boolean false
fileExtensions file type extension of files to process String Set {}

Examples

To configure the check: 

<module name="JavadocPackage"/>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

Checker

JavadocParagraph

Description

Checks that:

  • There is one blank line between each of two paragraphs and one blank line before the at-clauses block if it is present.
  • Each paragraph but the first has <p> immediately before the first word, with no space after.

Properties

name description type default value
allowNewlineParagraph whether the <p> tag should be placed immediately before the first word Boolean true

Examples

Default configuration: 

<module name="JavadocParagraph"/>

To allows to place text of a paragraph not immediately after a <p> tag: 

<module name="JavadocParagraph">
    <property name="allowNewlineParagraph" value="true"/>
</module>

In case of tagImmediatelyBeforeFirstWord set to false the following example will not have any violations: 

/**
 * Some Javadoc.
 *
 * <p>
 * Some Javadoc.
 *
 * <p>  Some Javadoc.
 *
 * <p>
 * <pre>
 * Some preformatted Javadoc.
 * </pre>
 *
 */

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocStyle

Description

Validates Javadoc comments to help ensure they are well formed. The following checks are performed:

  • Ensures the first sentence ends with proper punctuation (That is a period, question mark, or exclamation mark, by default). Javadoc automatically places the first sentence in the method summary table and index. Without proper punctuation the Javadoc may be malformed. All items eligible for the {@inheritDoc} tag are exempt from this requirement.
  • Check text for Javadoc statements that do not have any description. This includes both completely empty Javadoc, and Javadoc with only tags such as @param and @return.
  • Check text for incomplete HTML tags. Verifies that HTML tags have corresponding end tags and issues an "Unclosed HTML tag found:" error if not. An "Extra HTML tag found:" error is issued if an end tag is found without a previous open tag.
  • Check that a package Javadoc comment is well-formed (as described above) and NOT missing from any package-info.java files.
  • Check for allowed HTML tags. The list of allowed HTML tags is "a", "abbr", "acronym", "address", "area", "b", "bdo", "big", "blockquote", "br", "caption", "cite", "code", "colgroup", "dd", "del", "div", "dfn", "dl", "dt", "em", "fieldset", "font", "h1" to "h6", "hr", "i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", "samp", "small", "span", "strong", "sub", "sup", "table", "tbody", "td", "tfoot", "th", "thread", "tr", "tt", "u", "ul".

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.

Properties

name description type default value
scope visibility scope where Javadoc comments are checked scope private
excludeScope visibility scope where Javadoc comments are not checked scope null
checkFirstSentence Whether to check the first sentence for proper end of sentence. boolean true
endOfSentenceFormat Format for matching the end of a sentence. regular expression ([.?!][ \t\n\r\f<])|([.?!]$)
checkEmptyJavadoc Whether to check if the Javadoc is missing a describing text. boolean false
checkHtml Whether to check for incomplete HTML tags. boolean true
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. ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, PACKAGE_DEF, VARIABLE_DEF.

Examples

To configure the default check: 

<module name="JavadocStyle"/>

To configure the check for public scope: 

<module name="JavadocStyle">
   <property name="scope" value="public"/>
</module>

To configure the check for javadoc which is in private, but not in package scope: 

<module name="JavadocStyle">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="package"/>
</module>

To configure the check to turn off first sentence checking: 

<module name="JavadocStyle">
   <property name="checkFirstSentence" value="false"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocTagContinuationIndentation

Description

Checks the indentation of the continuation lines in at-clauses.

Properties

name description type default value
offset How many spaces to use for new indentation level. Integer 4

Examples

Default configuration 

<module name="JavadocTagContinuationIndentation">
    <property name="offset" value="4"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocType

Description

Checks Javadoc comments for class and interface definitions. By default, does not check for author or version tags. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to one of the Scope constants. To define the format for an author tag or a version tag, set property authorFormat or versionFormat respectively to a regular expression.

Does not perform checks for author and version tags for inner classes, as they should be redundant because of outer class.

Error messages about type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags.

Properties

name description type default value
scope visibility scope where Javadoc comments are checked scope private
excludeScope visibility scope where Javadoc comments are not checked scope null
authorFormat pattern for @author tag regular expression null (tag not required)
versionFormat pattern for @version tag regular expression null (tag not required)
allowMissingParamTags whether to ignore errors when a class has type parameters but does not have matching param tags in the javadoc. boolean false
allowUnknownTags whether to ignore errors when a Javadoc tag is not recognised. boolean false
tokens tokens to check subset of tokens INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF. INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF.

Examples

To configure the default check: 

<module name="JavadocType"/>

To configure the check for public scope: 

<module name="JavadocType">
   <property name="scope" value="public"/>
</module>

To configure the check for an @author tag: 

<module name="JavadocType">
   <property name="authorFormat" value="\S"/>
</module>

To configure the check for a CVS revision version tag: 

<module name="JavadocType">
   <property name="versionFormat" value="\$Revision.*\$"/>
</module>

To configure the check for private classes only: 

<module name="JavadocType">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="package"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocVariable

Description

Checks that variables have Javadoc comments. Ignores serialVersionUID fields.

Properties

name description type default value
scope visibility scope where Javadoc comments are checked scope private
excludeScope visibility scope where Javadoc comments are not checked scope null
ignoreNamePattern regexp to define variable names to ignore regular expression null
tokens tokens to check subset of tokens ENUM_CONSTANT_DEF. ENUM_CONSTANT_DEF.

Examples

To configure the default check: 

<module name="JavadocVariable"/>

To configure the check for public scope: 

<module name="JavadocVariable">
   <property name="scope" value="public"/>
</module>

To configure the check for members which are in private, but not in protected scope: 

<module name="JavadocVariable">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
</module>

To ignore absence of Javadoc comments for variables with names log or logger: 

<module name="JavadocVariable">
    <property name="ignoreNamePattern" value="log|logger"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

NonEmptyAtclauseDescription

Description

Checks that the at-clause tag is followed by description.

Examples

Default configuration that will check @param, @return, @throws, @deprecated: 

<module name="NonEmptyAtclauseDescription"/>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

SingleLineJavadoc

Description

Checks that a JavaDoc block can fit in a single line and doesn't contain at-clauses. Javadoc comment that contains at least one at-clause should be formatted in a few lines.

Properties

name description type default value
ignoredTags allows to specify at-clauses which are ignored by the check. String null
ignoreInlineTags whether inline tags must be ignored. Boolean true

Examples

Default configuration: 

<module name="SingleLineJavadoc"/>

To specify a list of ignored at-clauses and make inline at-clauses not ignored: 

<module name="SingleLineJavadoc">
    <property name="ignoredTags" value="@inheritDoc, @see"/>
    <property name="ignoreInlineTags" value="false"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

SummaryJavadoc

Description

Checks that Javadoc summary sentence does not contain phrases that are not recommended to use.

Properties

name description type default value
forbiddenSummaryFragments forbidden summary fragments regular expression ^$
period period symbol at the end of first javadoc sentence String literal .

Examples

By default Check validate that first sentence is not empty: 

<module name="SummaryJavadocCheck"/>

To ensure that summary do not contain phrase like "This method returns" , use following config: 

<module name="SummaryJavadocCheck">
    <property name="forbiddenSummaryFragments" value="^This method returns.*"/>
</module>

To specify period symbol at the end of first javadoc sentence: 

<module name="SummaryJavadocCheck">
    <property name="period" value="STRING_LITERAL"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

WriteTag

Description

Outputs a JavaDoc tag as information. Can be used e.g. with the stylesheets that sort the report by author name. To define the format for a tag, set property tagFormat to a regular expression. This check uses two different severity levels. The normal one is used for reporting when the tag is missing. The additional one (tagSeverity) is used for the level of reporting when the tag exists.

Properties

name description type default value
tag Name of tag String null
tagFormat Format of tag regular expression null
tagSeverity Severity level when tag is found and printed severity info
tokens tokens to check subset of tokens INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, METHOD_DEF, CTOR_DEF, ENUM_CONSTANT_DEF, ANNOTATION_FIELD_DEF. INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF.

Examples

An example of how to configure the check for printing author name is: 

<module name="WriteTag">
   <property name="tag" value="@author"/>
   <property name="tagFormat" value="\S"/>
</module>

An example of how to configure the check to print warnings if an "@incomplete" tag is found, and not print anything if it is not found: 

<module name="WriteTag">
   <property name="tag" value="@incomplete"/>
   <property name="tagFormat" value="\S"/>
   <property name="severity" value="ignore"/>
   <property name="tagSeverity" value="warning"/>
</module>

Example of Usage

Error Messages

All messages can be customized if the default message doesn't suite you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker