Content

AtclauseOrder

Since Checkstyle 6.0

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

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
target Specify the list of targets to check at-clauses. subset of tokens TokenTypes CLASS_DEF , INTERFACE_DEF , ENUM_DEF , METHOD_DEF , CTOR_DEF , VARIABLE_DEF 6.0
tagOrder Specify the order by tags. String Set @author, @deprecated, @exception, @param, @return, @see, @serial, @serialData, @serialField, @since, @throws, @version 6.0

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

Violation Messages

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

InvalidJavadocPosition

Since Checkstyle 8.23

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

Violation Messages

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

JavadocBlockTagLocation

Since Checkstyle 8.24

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 &#64; or place it inside {@code }, for example:

/**
 * &#64;serial literal in {@code @serial} Javadoc tag.
 */
        

Properties

name description type default value since
tags Specify the javadoc tags to process. String Set author, deprecated, exception, hidden, param, provides, return, see, serial, serialData, serialField, since, throws, uses, version 8.24
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.24

Examples

To configure the default check:

<module name="JavadocBlockTagLocation"/>
        

Example:

/**
 * Escaped tag &#64;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

Violation Messages

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

JavadocContentLocation

Since Checkstyle 8.27

Description

Checks that the Javadoc content begins from the same position for all Javadoc comments in the project. Any leading asterisks and spaces are not counted as the beginning of the content and are therefore ignored.

It is possible to enforce two different styles:

  • {@code first_line} - Javadoc content starts from the first line:
    /** Summary text.
      * More details.
      */
    public void method();
                
  • {@code second_line} - Javadoc content starts from the second line:
    /**
      * Summary text.
      * More details.
      */
    public void method();
                

Notes

This check does not validate the Javadoc summary itself nor its presence. The check will not report any violations for missing or malformed javadoc summary. To validate the Javadoc summary use SummaryJavadoc check.

The Documentation Comment Specification permits leading asterisks on the first line. For these Javadoc comments:

/***
  * Some text.
  */
/************
  * Some text.
  */
/**           **
  * Some text.
  */
        

The documentation generated will be just "Some text." without any asterisks. Since these asterisks will not appear in the generated documentation, they should not be considered as the beginning of the Javadoc content. In such cases, the check assumes that the Javadoc content begins on the second line.

Properties

name description type default value since
location Specify the policy on placement of the Javadoc content. Javadoc Content Location second_line 8.27

Examples

By default Check validate that the Javadoc content starts from the second line:

<module name="JavadocContentLocationCheck"/>
        

This setting produces a violation for each multi-line comment starting on the same line as the initial asterisks:

/** This comment causes a violation because it starts from the first line
  * and spans several lines.
  */
/**
  * This comment is OK because it starts from the second line.
  */
/** This comment is OK because it is on the single line. */
        

To ensure that Javadoc content starts from the first line:

<module name="JavadocContentLocationCheck">
  <property name="location" value="first_line"/>
</module>
        

This setting produces a violation for each comment not starting on the same line as the initial asterisks:

/** This comment is OK because it starts on the first line.
   * There may be additional text.
   */
/**
  * This comment causes a violation because it starts on the second line.
  */
/** This single-line comment also is OK. */
        

Example of Usage

Violation Messages

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

JavadocMethod

Since Checkstyle 3.0

Description

Checks the Javadoc of a method or constructor. 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 methods which return non-void but for which no return tag is present can be suppressed by defining property allowMissingReturnTag.

Violates exceptions which are declared to be thrown (by throws in the method signature or by throw new in the method body), but for which no throws tag is present by activation of property validateThrows. Note that throw new is not checked in the following places:

  • Inside a try block (with catch). It is not possible to determine if the thrown exception can be caught by the catch block as there is no knowledge of the inheritance hierarchy, so the try block is ignored entirely. However, catch and finally blocks, as well as try blocks without catch, are still checked.
  • Local classes, anonymous classes and lambda expressions. It is not known when the throw statements inside such classes are going to be evaluated, so they are ignored.

ATTENTION: Checkstyle does not have information about hierarchy of exception types so usage of base class is considered as separate exception type. As workaround you need to specify both types in javadoc (parent and exact type).

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)
        

Properties

name description type default value since
allowedAnnotations Specify the list of annotations that allow missed documentation. String Set Override 6.0
validateThrows Control whether to validate throws tags. Boolean false 6.0
scope Specify the visibility scope where Javadoc comments are checked. Scope private 3.0
excludeScope Specify the visibility scope where Javadoc comments are not checked. Scope null 3.4
allowMissingParamTags Control whether to ignore violations when a method has parameters but does not have matching param tags in the javadoc. Boolean false 3.1
allowMissingReturnTag Control whether to ignore violations when a method returns non-void type and does not have a return tag in the javadoc. Boolean false 3.1
tokens tokens to check subset of tokens METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF . METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF . 3.0

Examples

To configure the default check:

<module name="JavadocMethod"/>
        

To configure the check for public scope, ignoring any missing param tags is:

<module name="JavadocMethod">
  <property name="scope" value="public"/>
  <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 to validate throws tags, you can use following config.

<module name="JavadocMethod">
  <property name="validateThrows" value="true"/>
</module>
        
/**
 * Actual exception thrown is child class of class that is declared in throws.
 * It is limitation of checkstyle (as checkstyle does not know type hierarchy).
 * Javadoc is valid not declaring FileNotFoundException
 * BUT checkstyle can not distinguish relationship between exceptions.
 * @param file some file
 * @throws IOException if some problem
 */
public void doSomething8(File file) throws IOException {
    if (file == null) {
        throw new FileNotFoundException(); // violation
    }
}

/**
 * Exact throw type referencing in javadoc even first is parent of second type.
 * It is a limitation of checkstyle (as checkstyle does not know type hierarchy).
 * This javadoc is valid for checkstyle and for javadoc tool.
 * @param file some file
 * @throws IOException if some problem
 * @throws FileNotFoundException if file is not found
 */
public void doSomething9(File file) throws IOException {
    if (file == null) {
        throw new FileNotFoundException();
    }
}

/**
 * Ignore try block, but keep catch and finally blocks.
 *
 * @param s String to parse
 * @return A positive integer
 */
public int parsePositiveInt(String s) {
    try {
        int value = Integer.parseInt(s);
        if (value <= 0) {
            throw new NumberFormatException(value + " is negative/zero"); // ok, try
        }
        return value;
    } catch (NumberFormatException ex) {
        throw new IllegalArgumentException("Invalid number", ex); // violation, catch
    } finally {
        throw new IllegalStateException("Should never reach here"); // violation, finally
    }
}

/**
 * Try block without catch is not ignored.
 *
 * @return a String from standard input, if there is one
 */
public String readLine() {
    try (Scanner sc = new Scanner(System.in)) {
        if (!sc.hasNext()) {
            throw new IllegalStateException("Empty input"); // violation, not caught
        }
        return sc.next();
    }
}

/**
 * Lambda expressions are ignored as we do not know when the exception will be thrown.
 *
 * @param s a String to be printed at some point in the future
 * @return a Runnable to be executed when the string is to be printed
 */
public Runnable printLater(String s) {
    return () -> {
        if (s == null) {
            throw new NullPointerException(); // ok
        }
        System.out.println(s);
    };
}
        

Example of Usage

Violation Messages

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

JavadocMissingWhitespaceAfterAsterisk

Since Checkstyle 8.32

Description

Checks that there is at least one whitespace after the leading asterisk. Although spaces after asterisks are optional in the Javadoc comments, their absence makes the documentation difficult to read. It is the de facto standard to put at least one whitespace after the leading asterisk.

Properties

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3

Examples

To configure the default check:

<module name="JavadocMissingWhitespaceAfterAsterisk"/>
        

Code Example:

/** This is valid single-line Javadoc. */
class TestClass {
  /**
   *This is invalid Javadoc.
   */
  int invalidJavaDoc;
  /**
   * This is valid Javadoc.
   */
  void validJavaDocMethod() {
  }
  /**This is invalid single-line Javadoc. */
  void invalidSingleLineJavaDocMethod() {
  }
  /** This is valid single-line Javadoc. */
  void validSingleLineJavaDocMethod() {
  }
}
        

Example of Usage

Violation Messages

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

JavadocPackage

Since Checkstyle 5.0

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.

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

Properties

name description type default value since
allowLegacy Allow legacy package.html file to be used. Boolean false 5.0
fileExtensions Specify the file type extension of files to process. String Set .java 5.0

Examples

To configure the check:

<module name="JavadocPackage"/>
        

To configure the check to use legacy package.html file when package-info.java file is absent:

<module name="JavadocPackage">
  <property name="allowLegacy" value="true"/>
</module>
        

Example of Usage

Violation Messages

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

JavadocParagraph

Since Checkstyle 6.0

Description

Checks the Javadoc paragraph.

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 since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
allowNewlineParagraph Control whether the <p> tag should be placed immediately before the first word. Boolean true 6.9

Examples

To configure the default check:

<module name="JavadocParagraph"/>
        

By default, the check will report a violation if there is a new line or whitespace after the <p> tag:

/**
 * No tag (ok).
 *
 * <p>Tag immediately before the text (ok).
 * <p>No blank line before the tag (violation).
 *
 * <p>
 * New line after tag (violation).
 *
 * <p> Whitespace after tag (violation).
 *
 */
public class TestClass {
}
        

To allow newlines and spaces immediately after the <p> tag:

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

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

/**
 * No tag (ok).
 *
 * <p>Tag immediately before the text (ok).
 * <p>No blank line before the tag (violation).
 *
 * <p>
 * New line after tag (ok).
 *
 * <p> Whitespace after tag (ok).
 *
 */
public class TestClass {
}
        

Example of Usage

Violation Messages

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

JavadocStyle

Since Checkstyle 3.2

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", "dfn", "div", "dl", "dt", "em", "fieldset", "font", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", "samp", "small", "span", "strong", "sub", "sup", "table", "tbody", "td", "tfoot", "th", "thead", "tr", "tt", "u", "ul", "var".

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 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. Regular Expression "([.?!][ \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 . ANNOTATION_DEF , ANNOTATION_FIELD_DEF , CLASS_DEF , CTOR_DEF , ENUM_CONSTANT_DEF , ENUM_DEF , INTERFACE_DEF , METHOD_DEF , PACKAGE_DEF , VARIABLE_DEF . 3.2

Examples

To configure the default check:

<module name="JavadocStyle"/>
        

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="JavadocStyle">
<property name="scope" value="public"/>
</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="JavadocStyle">
<property name="scope" value="private"/>
<property name="excludeScope" value="package"/>
</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="JavadocStyle">
<property name="checkFirstSentence" value="false"/>
</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="JavadocStyle">
<property name="checkHtml" value="false"/>
</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="JavadocStyle">
<property name="tokens" value="CLASS_DEF"/>
</module>
        

Example:

/**
 * Some description here // violation, the sentence must end with a proper punctuation
 */
public class Test {
    /**
     * Some description here // OK
     */
    private void test1() {}
}
        

Example of Usage

Violation Messages

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

JavadocTagContinuationIndentation

Since Checkstyle 6.0

Description

Checks the indentation of the continuation lines in at-clauses. That is whether the continued description of at clauses should be indented or not. If the text is not properly indented it throws a violation. A continuation line is when the description starts/spans past the line with the tag. Default indentation required is at least 4, but this can be changed with the help of properties below.

Properties

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
offset Specify how many spaces to use for new indentation level. Integer 4 6.0

Examples

To configure the default check:

<module name="JavadocTagContinuationIndentation"/>
        

Example:

/**
 * @tag comment
 *  Indentation spacing is 1. Line with violation
 *   Indentation spacing is 2. Line with violation
 *     Indentation spacing is 4. OK
 */
public class Test {
}
        

To configure the check with two spaces indentation:

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

Example:

/**
 * @tag comment
 * Indentation spacing is 0. Line with violation
 *   Indentation spacing is 2. OK
 *  Indentation spacing is 1. Line with violation
 */
public class Test {
}
        

To configure the check to show violations for Tight-HTML Rules:

<module name="JavadocTagContinuationIndentation">
  <property name="violateExecutionOnNonTightHtml" value="true"/>
</module>
        

Example:

/**
 * <p> 'p' tag is unclosed. Line with violation, this html tag needs closing tag.
 * <p> 'p' tag is closed</p>. OK
 */
public class Test {
}
        

Example of Usage

Violation Messages

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

JavadocType

Since Checkstyle 3.0

Description

Checks the Javadoc comments for annotation/enum/class/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 since
scope Specify the visibility scope where Javadoc comments are checked. Scope private 3.0
excludeScope Specify the visibility scope where Javadoc comments are not checked. Scope null 3.4
authorFormat Specify the pattern for @author tag. Regular Expression null 3.0
versionFormat Specify the pattern for @version tag. Regular Expression null 3.0
allowMissingParamTags Control whether to ignore violations when a class has type parameters but does not have matching param tags in the Javadoc. Boolean false 4.0
allowUnknownTags Control whether to ignore violations when a Javadoc tag is not recognised. Boolean false 5.1
allowedAnnotations Specify the list of annotations that allow missed documentation. Only short names are allowed, e.g. Generated. String Set Generated 8.15
tokens tokens to check subset of tokens INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF . INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF . 3.0

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

Violation Messages

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

JavadocVariable

Since Checkstyle 3.0

Description

Checks that a variable has a Javadoc comment. Ignores serialVersionUID fields.

Properties

name description type default value since
scope Specify the visibility scope where Javadoc comments are checked. Scope private 3.0
excludeScope Specify the visibility scope where Javadoc comments are not checked. Scope null 3.4
ignoreNamePattern Specify the regexp to define variable names to ignore. Regular Expression null 5.8
tokens tokens to check subset of tokens ENUM_CONSTANT_DEF . ENUM_CONSTANT_DEF . 3.0

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

Violation Messages

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

MissingJavadocMethod

Since Checkstyle 8.21

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

name description type default value since
minLineCount Control the minimal amount of lines in method to allow no documentation. Integer -1 8.21
allowedAnnotations Configure the list of annotations that allow missed documentation. String Set Override 8.21
scope Specify the visibility scope where Javadoc comments are checked. Scope public 8.21
excludeScope Specify the visibility scope where Javadoc comments are not checked. Scope null 8.21
allowMissingPropertyJavadoc Control whether to allow missing Javadoc on accessor methods for properties (setters and getters). Boolean false 8.21
ignoreMethodNamesRegex ignore method whose names are matching specified regex. Regular Expression null 8.21
tokens tokens to check subset of tokens METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF . METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF . 8.21

Examples

To configure the default check:

<module name="MissingJavadocMethod"/>
        

Example:

public class Test {
  public Test() {} // violation, missing javadoc for constructor
  public void test() {} // violation, missing javadoc for method
  /**
   * Some description here.
   */
  public void test2() {} // OK

  @Override
  public String toString() { // OK
    return "Some string";
  }

  private void test1() {} // OK
  protected void test2() {} // OK
  void test3() {} // OK
}
        

To configure the check for private scope:

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

Example:

public class Test {
  private void test1() {} // violation, the private method is missing javadoc
}
        

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>
        

Example:

public class Test {
  private void test1() {} // violation, the private method is missing javadoc
  /**
   * Some description here
   */
  private void test1() {} // OK
  protected void test2() {} // OK
}
        

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

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

Example:

public class Test {
  public void test1() {} // violation, method is missing javadoc
  public void foo() {} // OK
  public void foobar() {} // OK
}
        

To configure the check for ignoring missing javadoc for accessor methods:

<module name="MissingJavadocMethod">
  <property name="allowMissingPropertyJavadoc" value="true"/>
</module>
          

Example:

public class Test {
  private String text;

  public void test() {} // violation, method is missing javadoc
  public String getText() { return text; } // OK
  public void setText(String text) { this.text = text; } // OK
}
        

To configure the check with annotations that allow missed documentation:

<module name="MissingJavadocMethod">
  <property name="allowedAnnotations" value="Override,Deprecated"/>
</module>
        

Example:

public class Test {
  public void test() {} // violation, method is missing javadoc
  @Override
  public void test1() {} // OK
  @Deprecated
  public void test2() {} // OK
  @SuppressWarnings
  public void test3() {} // violation, method is missing javadoc
  /**
   * Some description here.
   */
  @SuppressWarnings
  public void test4() {} // OK
}
        

Example of Usage

Violation Messages

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

MissingJavadocPackage

Since Checkstyle 8.22

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

Violation Messages

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

MissingJavadocType

Since Checkstyle 8.20

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

name description type default value since
scope specify the visibility scope where Javadoc comments are checked. Scope public 8.20
excludeScope specify the visibility scope where Javadoc comments are not checked. Scope null 8.20
skipAnnotations specify the list of annotations that allow missed documentation. Only short names are allowed, e.g. Generated. String Set Generated 8.20
tokens tokens to check subset of tokens INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF . INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF . 8.20

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

Violation Messages

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

NonEmptyAtclauseDescription

Since Checkstyle 6.0

Description

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

Properties

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
javadocTokens javadoc tokens to check subset of javadoc tokens PARAM_LITERAL , RETURN_LITERAL , THROWS_LITERAL , EXCEPTION_LITERAL , DEPRECATED_LITERAL . PARAM_LITERAL , RETURN_LITERAL , THROWS_LITERAL , EXCEPTION_LITERAL , DEPRECATED_LITERAL . 7.3

Examples

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

<module name="NonEmptyAtclauseDescription"/>
        

To configure the check to validate only @param and @return tags:

<module name="NonEmptyAtclauseDescription">
  <property name="javadocTokens" value="PARAM_LITERAL,RETURN_LITERAL"/>
</module>
        

Example of Usage

Violation Messages

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

SingleLineJavadoc

Since Checkstyle 6.0

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 since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
ignoredTags Specify at-clauses which are ignored by the check. String Set {} 6.8
ignoreInlineTags Control whether inline tags must be ignored. Boolean true 6.8

Examples

To configure the check:

<module name="SingleLineJavadoc"/>
        

To configure the check with 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

Violation Messages

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

SummaryJavadoc

Since Checkstyle 6.0

Description

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

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Boolean false 8.3
forbiddenSummaryFragments Specify the regexp for forbidden summary fragments. Regular Expression "^$" (empty) 6.0
period Specify the period symbol at the end of first javadoc sentence. String "." 6.2

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

Violation Messages

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

WriteTag

Since Checkstyle 4.2

Description

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

name description type default value since
tag Specify the name of tag. String null 4.2
tagFormat Specify the regexp to match tag content. Regular Expression null 4.2
tagSeverity Specify the severity level when tag is found and printed. Severity info 4.2
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 . 4.2

Examples

To configure the check for printing author name:

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

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

Violation Messages

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