Description

Checks the order of javadoc block-tags or javadoc tags.

Note: Google used the term "at-clauses" for block tags in their guide till 2017-02-28.

Properties

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

• Google Style
• Checkstyle Style

Violation Messages

• at.clause.order
• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Checks that Javadocs are located at the correct position. As specified at Documentation Comment Specification for the Standard Doclet, Javadocs are recognized only when placed immediately before module, package, class, interface, constructor, method, or field declarations. Any other position, like in the body of a method, will be ignored by the javadoc tool and is considered invalid by this check.

Examples

To configure the check:

<module name="InvalidJavadocPosition"/>
        

The following code produces a violation because Javadocs should be before all annotations of the Javadoc's target:

@SuppressWarnings("serial")
/**
 * This comment looks like javadoc but it at an invalid location.
 * Therefore, the text will not get into TestClass.html and the check will produce a violation.
 */
public class TestClass {
}
        

Example of Usage

• Google Style
• Sun Style
• Checkstyle Style

Violation Messages

• invalid.position

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Checks that a javadoc block tag appears only at the beginning of a line, ignoring leading asterisks and white space. A block tag is a token that starts with @ symbol and is preceded by a whitespace. This check ignores block tags in comments and inside inline tags {@code } and {@literal }.

Rationale: according to the specification all javadoc block tags should be placed at the beginning of a line. Tags that are not placed at the beginning are treated as plain text. To recognize intentional tag placement to text area it is better to escape the @ symbol, and all non-escaped tags should be located at the beginning of the line. See NOTE section for details on how to escape.

Notes

To place a tag explicitly as text, escape the @ symbol with HTML entity @ or place it inside {@code }, for example:

/**
 * @serial literal in {@code @serial} Javadoc tag.
 */
        

Properties

Examples

To configure the default check:

<module name="JavadocBlockTagLocation"/>
        

Example:

/**
 * Escaped tag @version (OK)
 * Plain text with {@code @see} (OK)
 * A @custom tag (OK)
 * 
 * email@author (OK)
 * (@param in parentheses) (OK)
 * '@param in single quotes' (OK)
 * @since 1.0 (OK)
 * text @return (violation)
 * * @param (violation)
+* @serial (violation)
 * @see first (OK) @see second (violation)
 */
public int field;
        

To configure the check to verify tags from JEP 8068562 only:

<module name="JavadocBlockTagLocation">
  <property name="tags" value="apiNote, implSpec, implNote"/>
</module>
        

To configure the check to verify all default tags and some custom tags in addition:

<module name="JavadocBlockTagLocation">
  <!-- default tags -->
  <property name="tags" value="author, deprecated, exception, hidden"/>
  <property name="tags" value="param, provides, return, see, serial"/>
  <property name="tags" value="serialData, serialField, since, throws"/>
  <property name="tags" value="uses, version"/>
  <!-- additional tags used in the project -->
  <property name="tags" value="noinspection"/>
</module>
        

Example of Usage

• Checkstyle Style

Violation Messages

• javadoc.blockTagLocation
• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 3.0

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.

Violates parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags. Violates exceptions which are declared to be thrown, but for which no throws tag is present can be suppressed by defining property allowMissingThrowsTags. Violates 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

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>
        

Example of Usage

• Google Style
• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.classInfo
• javadoc.duplicateTag
• javadoc.expectedTag
• javadoc.invalidInheritDoc
• javadoc.return.expected
• javadoc.unusedTag
• javadoc.unusedTagGeneral

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 5.0

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.

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

Properties

Examples

To configure the check:

<module name="JavadocPackage"/>
        

Example of Usage

• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.legacyPackageHtml
• javadoc.packageInfo

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

Checker

Description

Since Checkstyle 6.0

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

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

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.paragraph.line.before
• javadoc.paragraph.misplaced.tag
• javadoc.paragraph.redundant.paragraph
• javadoc.paragraph.tag.after
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 3.2

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

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

• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.empty
• javadoc.extraHtml
• javadoc.incompleteTag
• javadoc.missing
• javadoc.noPeriod
• javadoc.unclosedHtml

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 6.0

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

Properties

Examples

Default configuration

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

Example of Usage

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag
• tag.continuation.indent

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 3.0

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

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 that allows missing comments for classes annotated with @SpringBootApplication and @Configuration:

@SpringBootApplication // no violations about missing comment on class
public class Application {}

@Configuration // no violations about missing comment on class
class DatabaseConfiguration {}
        

Use following configuration:

<module name="JavadocType">
  <property name="allowedAnnotations" value="SpringBootApplication,Configuration"/>
</module>
        

Example of Usage

• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.unknownTag
• javadoc.unusedTag
• javadoc.unusedTagGeneral
• type.missingTag
• type.tagFormat

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 3.0

Checks that variables have Javadoc comments. Ignores serialVersionUID fields.

Properties

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

• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.missing

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Checks for missing Javadoc comments for a method or constructor. The scope to verify is specified using the Scope class and defaults to Scope.PUBLIC. To verify another scope, set property scope to a different scope.

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.

For getters and setters for the property allowMissingPropertyJavadoc, the 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;
}
        

Properties

Examples

To configure the default check:

<module name="MissingJavadocMethod"/>
        

To configure the check for private scope:

<module name="MissingJavadocMethod">
  <property name="scope" value="private"/>
</module>
        

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

<module name="MissingJavadocMethod">
  <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="MissingJavadocMethod">
  <property name="ignoreMethodNamesRegex" value="^foo.*$"/>
</module>
        

Example of Usage

• Google Style
• Sun Style
• Checkstyle Style

Violation Messages

• javadoc.missing

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Checks for missing Javadoc comments in package-info.java files.

Rationale: description and other related documentation for a package can be written up in the package-info.java file and it gets used in the production of the Javadocs. See link for more info.

Examples

To configure the check:

<module name="MissingJavadocPackage"/>
        

Example:

/**
* Provides API classes
*/
package com.checkstyle.api; // no violation
/*
* Block comment is not a javadoc
*/
package com.checkstyle.api; // violation
        

Example of Usage

• Checkstyle Style

Violation Messages

• package.javadoc.missing

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Checks for missing Javadoc comments for class, enum, interface, and annotation interface definitions. The scope to verify is specified using the Scope class and defaults to Scope.PUBLIC. To verify another scope, set property scope to one of the Scope constants.

Properties

Examples

To configure the default check to make sure all public class, enum, interface, and annotation interface, definitions have javadocs:

<module name="MissingJavadocType"/>
        

Example:

public class PublicClass {} // violation
private class PublicClass {}
protected class PublicClass {}
class PackagePrivateClass {}
        

To configure the check for private scope:

<module name="MissingJavadocType">
  <property name="scope" value="private"/>
</module>
        

Example:

public class PublicClass {} // violation
private class PublicClass {} // violation
protected class PublicClass {} // violation
class PackagePrivateClass {} // violation
        

To configure the check for private classes only:

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

Example:

public class PublicClass {}
private class PublicClass {} // violation
protected class PublicClass {}
class PackagePrivateClass {}
        

Example that allows missing comments for classes annotated with @SpringBootApplication and @Configuration:

@SpringBootApplication // no violations about missing comment on class
public class Application {}

@Configuration // no violations about missing comment on class
class DatabaseConfiguration {}
        

Use following configuration:

<module name="MissingJavadocType">
  <property name="skipAnnotations" value="SpringBootApplication,Configuration"/>
</module>
        

Example of Usage

• Checkstyle Style

Violation Messages

• javadoc.missing

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 6.0

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

Properties

Examples

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

<module name="NonEmptyAtclauseDescription"/>
        

Example of Usage

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag
• non.empty.atclause

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 6.0

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

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

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag
• singleline.javadoc

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 6.0

Checks that Javadoc summary sentence does not contain phrases that are not recommended to use. Summaries that contain only the {@inheritDoc} tag are skipped. Check also violate javadoc that does not contain first sentence.

Properties

Examples

By default Check validate that first sentence is not empty and first sentence is not missing:

<module name="SummaryJavadocCheck"/>
        

Example of {@inheritDoc} without summary.

        
public class Test extends Exception {
//Valid
  /**
   * {@inheritDoc}
   */
  public String ValidFunction(){
    return "";
  }
  //Violation
  /**
   *
   */
  public String InvalidFunction(){
    return "";
  }
}
      
        

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="。"/>
</module>
        

Example of period property.

public class TestClass {
  /**
  * This is invalid java doc.
  */
  void invalidJavaDocMethod() {
  }
  /**
  * This is valid java doc。
  */
  void validJavaDocMethod() {
  }
}
        

Example of Usage

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.wrong.singleton.html.tag
• summary.first.sentence
• summary.javaDoc
• summary.javaDoc.missing

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

Description

Since Checkstyle 4.2

Requires user defined JavaDoc tag to be present in javadoc comment with defined format. To define the format for a tag, set property tagFormat to a regular expression. Property tagSeverity is used for severity of events when the tag exists.

Properties

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

• Checkstyle Style

Violation Messages

• javadoc.writeTag
• type.missingTag
• type.tagFormat

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

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker