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>

Example1:

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

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

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

  /** */
  @Generated
  public class ClassG<T> {}
}

To configure the check for public scope: 

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

Example2:

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

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

  /** */
  private class ClassF<T> {}

  /** */
  @Generated
  public class ClassG<T> {}
}

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>

Example3:

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

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

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

  /** */
  @Generated
  public class ClassG<T> {}
}

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>

Example4:

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

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

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

  /** */
  @Generated
  public class ClassG<T> {}
}

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>

Example5:

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

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

  /** */
  public class ClassD {}

  /** */
  public class ClassE<T> {}

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

  /** */
  @Generated
  public class ClassG<T> {}
}

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>

Example6:

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

  /** */
  public class ClassE<T> {}

  /** */
  private class ClassF<T> {}

  /** */
  @Generated
  public class ClassG<T> {}
}

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>

Example7:

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

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

  /** */
  public class ClassD {}

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

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

  /** */
  @Generated
  public class ClassG<T> {}
}

To configure a check that allows skipping validation at all for classes annotated with @unknownTag 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocType">
      <property name="allowedAnnotations" value="unknownTag"/>
    </module>
  </module>
</module>

Example8: 

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

  /**
   * @author
   * @version abc
   * @unknownTag value
   */
  public class ClassC {}
  // violation 3 lines above 'Unknown tag 'unknownTag''
  /** */
  public class ClassD {}

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

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

  /** */
  @Generated // violation, 'Type Javadoc comment is missing @param <T> tag'
  public class ClassG<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