JavadocMethod

Since Checkstyle 3.0

Description

Checks the Javadoc of a method or constructor.

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
accessModifiers	Specify the access modifiers where Javadoc comments are checked.	AccessModifierOption[]	`public, protected, package, private`	8.42
allowInlineReturn	Control whether to allow inline return tags.	boolean	`false`	10.23.0
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
allowedAnnotations	Specify annotations that allow missed documentation.	String[]	`Override`	6.0
validateThrows	Control whether to validate `throws` tags.	boolean	`false`	6.0
tokens	tokens to check	subset of tokens METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF .	METHOD_DEF , CTOR_DEF , ANNOTATION_FIELD_DEF , COMPACT_CTOR_DEF .	3.0

Examples

To configure the default check:


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

Example:


public class Example1 {

  /** */
  Example1(int x) {}
  // violation above, 'Expected @param tag for 'x'.'
  /** */
  public int m1(int p1) throws IOException {
    // 2 violations above:
    //    '@return tag should be present and have description.'
    //    'Expected @param tag for 'p1'.'

    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }
  // violation 4 lines above '@return tag should be present and have description.'
  /** */
  void m3(int p1) {}
  // violation above, 'Expected @param tag for 'p1'.'
  /**
   * {@return the foo}
   */
  public int getFoo() {
    // violation above, '@return tag should be present and have description.'
    return 0;
  }
}

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


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
      <property name="accessModifiers" value="public"/>
      <property name="allowMissingParamTags" value="true"/>
    </module>
  </module>
</module>

Example:


public class Example2 {

  /** */
  Example2(int x) {}

  /** */
  public int m1(int p1) throws IOException {
    // violation above, '@return tag should be present and have description.'
    /*
     ok, allowMissingParamTags is true
    */
    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }

  /** */
  void m3(int p1) {}

  /**
   * {@return the foo}
   */
  public int getFoo() {
    // violation above, '@return tag should be present and have description.'
    return 0;
  }
}

To configure the check to ignore any missing return tags:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
        <property name="allowMissingReturnTag" value="true"/>
    </module>
  </module>
</module>

Example:


public class Example4 {

  /** */
  Example4(int x) {}
  // violation above, 'Expected @param tag for 'x'.'
  /** */
  public int m1(int p1) throws IOException {
    // violation above, 'Expected @param tag for 'p1'.'
    /*
     ok, allowMissingReturnTag is true
    */
    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }

  /** */
  void m3(int p1) {}
  // violation above, 'Expected @param tag for 'p1'.'
  /**
   * {@return the foo}
   */
  public int getFoo() {

    return 0;
  }
}

To configure the check to ignore Methods with annotation Deprecated:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
        <property name="allowedAnnotations" value="Deprecated"/>
    </module>
  </module>
</module>

Example:


public class Example5 {

  /** */
  Example5(int x) {}
  // violation above, 'Expected @param tag for 'x'.'
  /** */
  public int m1(int p1) throws IOException {
    // 2 violations above:
    //    '@return tag should be present and have description.'
    //    'Expected @param tag for 'p1'.'

    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }

  /** */
  void m3(int p1) {}
  // violation above, 'Expected @param tag for 'p1'.'
  /**
   * {@return the foo}
   */
  public int getFoo() {
    // violation above, '@return tag should be present and have description.'
    return 0;
  }
}

To configure the check only for tokens which are Constructor Definitions:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
      <property name="tokens" value="CTOR_DEF"/>
    </module>
  </module>
</module>

Example:


public class Example6 {

  /** */
  Example6(int x) {}
  // violation above, 'Expected @param tag for 'x''
  /** */
  public int m1(int p1) throws IOException {
    /*
     ok, only constructors are checked.
     Method definitions are ignored for this token set.
    */
    throw new IOException();
  }
  // ok, only constructors are checked
  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }
  // ok, only constructors are checked
  /** */
  void m3(int p1) {}
  // ok, only constructors are checked
  /**
   * {@return the foo}
   */
  public int getFoo() {

    return 0;
  }
}

To configure the check to validate throws tags, you can use following config.


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
      <property name="validateThrows" value="true"/>
    </module>
  </module>
</module>

Example:


public class Example7 {

  /** */
  Example7(int x) {}
  // violation above, 'Expected @param tag for 'x'.'
  /** */
  public int m1(int p1) throws IOException {
    // 3 violations above:
    //    '@return tag should be present and have description.'
    //    'Expected @param tag for 'p1'.'
    //    'Expected @throws tag for 'IOException'.'
    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }
  // violation 4 lines above '@return tag should be present and have description.'
  /** */
  void m3(int p1) {}
  // violation above, 'Expected @param tag for 'p1'.'
  /**
   * {@return the foo}
   */
  public int getFoo() {
    // violation above, '@return tag should be present and have description.'
    return 0;
  }
}

To configure the check to allow inline return tags, you can use following config.


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
        <property name="allowInlineReturn" value="true"/>
    </module>
  </module>
</module>

Example:


public class Example8 {

  /** */
  Example8(int x) {}
  // violation above, 'Expected @param tag for 'x'.'
  /** */
  public int m1(int p1) throws IOException {
    // 2 violations above:
    //    '@return tag should be present and have description.'
    //    'Expected @param tag for 'p1'.'

    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }
  // violation 4 lines above '@return tag should be present and have description.'
  /** */
  void m3(int p1) {}
  // violation above, 'Expected @param tag for 'p1'.'
  /**
   * {@return the foo}
   */
  public int getFoo() {
    // ok, allowInlineReturn is true
    return 0;
  }
}

To configure the check for methods which are in private and package, but not any other modifier:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocMethod">
      <property name="accessModifiers" value="private, package"/>
    </module>
  </module>
</module>

Example:


public class Example3 {

  /** */
  Example3(int x) {}

  /** */
  public int m1(int p1) throws IOException {
    /*
     ok, only private and package access modifiers are checked.
     Public methods are not validated under this configuration.
    */
    throw new IOException();
  }

  /**
   * @param p1 The first number
   */
  @Deprecated
  private int m2(int p1) {
    return p1;
  }

  /** */
  void m3(int p1) {}

  /**
   * {@return the foo}
   */
  public int getFoo() {

    return 0;
  }
}

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.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

TreeWalker