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:


/**
   * <a> 'a' tag is not closed
   */
class Example1 {

  /**
   * @param input comment with
   *     indentation spacing for the tag
   */
  public void testIndentation4(String input) {}
   // ok, Default expected Indentation is 4

  /**
   * @param input comment with
   *   indentation spacing for the tag
   */
  public void testIndentation2(String input) {}
   // violation 3 lines above 'Line continuation have incorrect indentation level'

  /**
   * <pre>
   * this content, and not any error:
   *   "JavadocTagContinuation do not validate lines contained in Pre tag,
   *   No violation is expected here."</pre>
   */
  public void testMethodPre(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 testMethodCode(String input) {}

  /**
   * Test class.
   *
   * @param input comment with
   *          This is the predefined indentation applied by Eclipse formatter.
   */
  public void testIndentationEclipse(String input) {}
}

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:


/**
   * <a> 'a' tag is not closed
   */
class Example2 {

  /**
   * @param input comment with
   *     indentation spacing for the tag
   */
  public void testIndentation4(String input) {}
   // ok, Indentation above 1 is fine as offset value is 2

  /**
   * @param input comment with
   *   indentation spacing for the tag
   */
  public void testIndentation2(String input) {}
   // ok, Indentation above 1 is fine as offset value is 2

  /**
   * <pre>
   * this content, and not any error:
   *   "JavadocTagContinuation do not validate lines contained in Pre tag,
   *   No violation is expected here."</pre>
   */
  public void testMethodPre(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 testMethodCode(String input) {}

  /**
   * Test class.
   *
   * @param input comment with
   *          This is the predefined indentation applied by Eclipse formatter.
   */
  public void testIndentationEclipse(String input) {}
}

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:


/**
   * <a> 'a' tag is not closed
   */
class Example3 {
  // violation 3 lines above 'Unclosed HTML tag found: a'

  /**
   * @param input comment with
   *     indentation spacing for the tag
   */
  public void testIndentation4(String input) {}
   // ok, Default expected Indentation is 4

  /**
   * @param input comment with
   *   indentation spacing for the tag
   */
  public void testIndentation2(String input) {}
   // violation 3 lines above 'Line continuation have incorrect indentation level'

  /**
   * <pre>
   * this content, and not any error:
   *   "JavadocTagContinuation do not validate lines contained in Pre tag,
   *   No violation is expected here."</pre>
   */
  public void testMethodPre(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 testMethodCode(String input) {}

  /**
   * Test class.
   *
   * @param input comment with
   *          This is the predefined indentation applied by Eclipse formatter.
   */
  public void testIndentationEclipse(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