JavadocType

Since Checkstyle 3.0

Description

Checks the Javadoc comments for type 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 pattern.

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

Does not perform checks for type definitions that do not have any Javadoc comments.

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

Properties

name description type default value since
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 annotations that allow skipping validation at all. Only short names are allowed, e.g. Generated. String[] Generated 8.15
authorFormat Specify the pattern for @author tag. Pattern null 3.0
excludeScope Specify the visibility scope where Javadoc comments are not checked. Scope null 3.4
scope Specify the visibility scope where Javadoc comments are checked. Scope private 3.0
versionFormat Specify the pattern for @version tag. Pattern null 3.0
tokens tokens to check subset of tokens INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , RECORD_DEF . INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , RECORD_DEF . 3.0

Examples

To configure the default check: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocType"/>
  </module>
</module>

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK
}

/**
 * @author
 * @version abc
 * @unknownTag value // violation
 */
public class ClassC {} // OK

/** */
public class ClassD<T> {} // violation, as param tag for <T> is missing

/** */
private class ClassE<T> {} // violation, as param tag for <T> is missing

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check for public scope: 

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

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK
}

/**
 * @author
 * @version abc
 * @unknownTag value // violation
 */
public class ClassC {} // OK

/** */
public class ClassD<T> {} // violation, as param tag for <T> is missing

/** */
private class ClassE<T> {} // OK

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check for an @author tag: 

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

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK, as author tag check is ignored for inner class
}

/**
 * @author
 * @version abc
 * @unknownTag value // violation
 */
public class ClassC {} // violation, as author format with only whitespace or new line is invalid

/** */
public class ClassD {} // violation, as author tag is missing

/** */
private class ClassE {} // violation, as author tag is missing

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check for a CVS revision version tag: 

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

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK, as version tag check is ignored for inner class
}

/**
 * @author
 * @version abc
 * @unknownTag value // violation
 */
public class ClassC {} // violation, as version format is invalid

/** */
public class ClassD {} // violation, as version tag is missing

/** */
private class ClassE {} // violation, as version tag is missing

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check for private classes only: 

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

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK
}

/**
 * @author
 * @version abc
 * @unknownTag value // OK
 */
public class ClassC {} // OK

/** */
public class ClassD<T> {} // OK

/** */
private class ClassE<T> {} // violation, as param tag for <T> is missing

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check that allows missing @param tags: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocType">
      <property name="allowMissingParamTags" value="true"/>
    </module>
  </module>
</module>

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
    /** */
    private class ClassB {} // OK
}

/**
 * @author
 * @version abc
 * @unknownTag value // violation
 */
public class ClassC {} // OK

/** */
public class ClassD<T> {} // OK, as missing param tag is allowed

/** */
private class ClassE<T> {} // OK, as missing param tag is allowed

/** */
@Generated
public class ClassF<T> {} // OK

To configure the check that allows unknown tags: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocType">
      <property name="allowUnknownTags" value="true"/>
    </module>
  </module>
</module>

Example:

/**
 * @author a
 * @version $Revision1$
 */
public class ClassA { // OK
  /** */
  private class ClassB {} // OK
}

/**
 * @author
 * @version abc
 * @unknownTag value // OK, as unknown tag is allowed
 */
public class ClassC {} // OK

/** */
public class ClassD {} // OK

/** */
private class ClassE {} // OK

/** */
@Generated
public class ClassF<T> {} // OK

To configure a check that allows skipping validation at all for classes annotated with @SpringBootApplication and @Configuration: 

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

Example: 

/** */
@SpringBootApplication // no violations about missing param tag on class
public class Application<T> {}

/** */
@Configuration // no violations about missing param tag on class
class DatabaseConfiguration<T> {}

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