SingleLineJavadoc

Since Checkstyle 6.0

Description

Checks that a Javadoc block can fit in a single-line and doesn't contain block tags. Javadoc comment that contains at least one block tag should be formatted in a few lines.

Properties

name description type default value since
ignoreInlineTags Control whether inline tags must be ignored. boolean true 6.8
ignoredTags Specify block tags which are ignored by the check. String[] {} 6.8
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 check: 

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

Example: 

public class Example1 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

To configure the check with a list of ignored block tags: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="ignoredTags" value="@inheritDoc, @see"/>
    </module>
  </module>
</module>

Example: 

public class Example2 {
  /** @see Math */
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

To configure the check to not ignore inline tags: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="ignoreInlineTags" value="false"/>
    </module>
  </module>
</module>

Example: 

public class Example3 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  // violation below, 'Javadoc comment should be multi-line'
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SingleLineJavadoc">
      <property name="violateExecutionOnNonTightHtml" value="true"/>
    </module>
  </module>
</module>

Example: 

public class Example4 {
  /** @see Math */ // violation, 'Javadoc comment should be multi-line'
  public int foo() {
    return 42;
  }

  /**
   * @return 42
   */
  public int bar() {
    return 42;
  }
  //ok below, because inline tag is ignored
  /** {@link #equals(Object)} */
  public int baz() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question
   */ // violation above, 'Unclosed HTML tag found'
  public int magic() {
    return 42;
  }

  /**
   * <p>the answer to the ultimate question</p>
   */
  public int foobar() {
    return 42;
  }
}

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