JavadocTagContinuationIndentation

Since Checkstyle 6.0

Description

Checks the indentation of the continuation lines in block tags. 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.

Notes

This check does not validate the indentation of lines inside pre tags.

Properties

name	description	type	default value	since
offset	Specify how many spaces to use for new indentation level.	int	`4`	6.0
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="Checker">
  <module name="TreeWalker">
    <module name="JavadocTagContinuationIndentation"/>
  </module>
</module>

Example:


/**
 * <p> 'p' tag is unclosed
 * <p> 'p' tag is closed</p>
 */
class Example1 {

  /**
   * @tag comment
   *     Indentation spacing is 4
   */
  public void testMethod1(String input) {
    // ok, Default expected Indentation is 4
  }

  /**
   * @tag comment
   *   Indentation spacing is 2
   */
  public void testMethod2(String input) {
    // violation 3 lines above 'Line continuation have incorrect indentation level'
  }
}

To configure the check with two spaces indentation:


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

Example:


/**
 * <p> 'p' tag is unclosed
 * <p> 'p' tag is closed</p>
 */
class Example2 {

  /**
   * @tag comment
   *     Indentation spacing is 4
   */
  public void testMethod1(String input) {
    // ok, Indentation above 1 is fine as offset value is 2
  }

  /**
   * @tag comment
   *   Indentation spacing is 2
   */
  public void testMethod2(String input) {
    // ok, Indentation above 1 is fine as offset value is 2
  }
}

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


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

Example:


/**
 * <p> 'p' tag is unclosed
 * <p> 'p' tag is closed</p>
 */
class Example3 {
  // violation 4 lines above 'Unclosed HTML tag found: p'
  /**
   * @tag comment
   *     Indentation spacing is 4
   */
  public void testMethod1(String input) {
    // ok, Default expected Indentation is 4
  }

  /**
   * @tag comment
   *  Indentation spacing is 1
   */
  public void testMethod2(String input) {
    // violation 3 lines above 'Line continuation have incorrect indentation level'
  }
}

Check does not validate the indentation of lines inside pre tags. Example:


class Example4 {

   /**
   * Writes the object using a
   * <a href="{@docRoot}/serialized-form.html#java.time.Ser">dedicated form</a>.
   * @serialData
   * <pre>
   * out.writeByte(1);
   * out.writeInt(nanos);
   * </pre>
   */
  public void testMethod1(String input) {}

  /**
   * Writes the object using a
   * <a href="{@docRoot}/serialized-form.html#java.time.Ser">dedicated form</a>.
   * @serialData
   * <code> // violation
   * out.writeByte(1); // violation
   * out.writeInt(nanos); // violation
   * </code> // violation
   */
  public void testMethod2(String input) {}

  /**
   * Test class.
   *
   * @apiNote
   *          This is the predefined indentation applied by Eclipse formatter.
   *          <pre>
   * this content, and not any error:
   *   "JavadocTagContinuation do not validate lines contained in Pre tag,
   *   No violation is expected here."</pre>
   */
  public void testMethod3(String input) {}

}

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