Checks the order of at-clauses.
| 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 |
Default configuration
com.puppycrawl.tools.checkstyle.checks.javadoc
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.
| 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. |
To configure the default check:
To configure the check for public
scope and to allow documentation of undeclared
RuntimeExceptions:
To configure the check for for public
scope, to allow documentation of undeclared RuntimeExceptions,
while ignoring any missing param tags is:
To configure the check for methods which are in private , but not in protected scope:
To configure the check for ignoring methods named foo(),foo1(),foo2(), etc.:
com.puppycrawl.tools.checkstyle.checks.javadoc
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.
| 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 | {} |
To configure the check:
com.puppycrawl.tools.checkstyle.checks.javadoc
Checks that:
| name | description | type | default value |
|---|---|---|---|
| allowNewlineParagraph | whether the <p> tag should be placed immediately before the first word | Boolean | true |
Default configuration:
To allows to place text of a paragraph not immediately after a <p> tag:
In case of tagImmediatelyBeforeFirstWord set to false the following example will not have any violations:
com.puppycrawl.tools.checkstyle.checks.javadoc
Validates Javadoc comments to help ensure they are well formed. The following checks are performed:
{@inheritDoc} tag are exempt from this
requirement.
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 |
|---|---|---|---|
| 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. |
To configure the default check:
To configure the check for public
scope:
To configure the check for javadoc which is in private, but not in package scope:
To configure the check to turn off first sentence checking:
com.puppycrawl.tools.checkstyle.checks.javadoc
Checks the indentation of the continuation lines in at-clauses.
| name | description | type | default value |
|---|---|---|---|
| offset | How many spaces to use for new indentation level. | Integer | 4 |
Default configuration
com.puppycrawl.tools.checkstyle.checks.javadoc
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.
| 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. |
To configure the default check:
To configure the check for public scope:
To configure the check for an @author tag:
To configure the check for a CVS revision version tag:
To configure the check for private classes only:
com.puppycrawl.tools.checkstyle.checks.javadoc
Checks that variables have Javadoc comments. Ignores serialVersionUID
fields.
| 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. |
To configure the default check:
To configure the check for public
scope:
To configure the check for members which are in private, but not in protected scope:
To ignore absence of Javadoc comments for variables with names log or logger:
com.puppycrawl.tools.checkstyle.checks.javadoc
Checks that the at-clause tag is followed by description.
Default configuration that will check @param, @return,
@throws, @deprecated:
com.puppycrawl.tools.checkstyle.checks.javadoc
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.
| 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 |
Default configuration:
To specify a list of ignored at-clauses and make inline at-clauses not ignored:
com.puppycrawl.tools.checkstyle.checks.javadoc
Checks that Javadoc summary sentence does not contain phrases that are not recommended to use.
| name | description | type | default value |
|---|---|---|---|
| forbiddenSummaryFragments | forbidden summary fragments | regular expression | ^$ |
| period | period symbol at the end of first javadoc sentence | String literal | . |
By default Check validate that first sentence is not empty:
To ensure that summary do not contain phrase like "This method returns" , use following config:
To specify period symbol at the end of first javadoc sentence:
com.puppycrawl.tools.checkstyle.checks.javadoc
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.
| 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. |
An example of how to configure the check for printing author name is:
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:
com.puppycrawl.tools.checkstyle.checks.javadoc