JavadocLeadingAsteriskAlign

Since Checkstyle 10.18.0

Description

Checks the alignment of leading asterisks in a Javadoc comment. The Check ensures that leading asterisks are aligned vertically under the first asterisk ( * ) of opening Javadoc tag. The alignment of closing Javadoc tag ( */ ) is also checked. If a closing Javadoc tag contains non-whitespace character before it then it's alignment will be ignored. If the ending javadoc line contains a leading asterisk, then that leading asterisk's alignment will be considered, the closing Javadoc tag will be ignored.

If you're using tabs then specify the the tab width in the tabWidth property.

Properties

name description type default value since
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 10.18

Examples

To configure the check: 

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

Example with correct alignment: 

/** Title
 * Javadoc for class
 */
public class Example1 {

  /** javadoc for instance variable. */
  private int ball;

  /**
   * Javadoc for instance variable
   */
  private int age;

  /**
   Javadoc for method. */
  private void foo() {}

  /**
    Javadoc for Constructor.
    This javadoc is allowed because there is no leading asterisk.
   */
  public Example1() {}

  /**
   * Javadoc for enum.
   */
  private enum correctJavadocEnum {
    /**
     * Correct Indentation for leading asterisk */
    ONE,

    /**
     Allowed because there are non-whitespace characters before the ending block. */
    TWO
  }
}

Example with incorrect alignment: 

/** Title
* Javadoc for class // violation
    */ // violation
public class Example2 {
  /**
    *  Javadoc for instance variable. // violation
    */ // violation
  private String name;

  /**
  *  Javadoc for method. // violation
  */ // violation
  private void foo() {}

  /**
   Javadoc for Constructor.
*/ // violation
  private Example2() {}

  /**
    * Javadoc for enum. // violation
   */
  private enum incorrectJavadocEnum {

    /**
    *  // violation
     */
    ONE,

    /**
        * Incorrect indentation for leading asterisk. */ // violation
    TWO,

    /**
 *    // violation
     */
    THREE
  }
}

To configure the check with tabWidth property: 

<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocLeadingAsteriskAlign">
      <property name="tabWidth" value="2"/>
    </module>
  </module>
</module>

Example: 

/**
 * Example with `tabWidth` property.
 * This example contains Tabs as well as Spaces.
 */
public class Example3 {
  /** <- Preceded with Tabs.
   * <- Preceded with Tabs & Spaces.
   */ // <- Preceded with Tabs & Spaces.
  private String name;

  /** <- Preceded with Spaces.
   * <- Preceded with Tabs.
   */ // <- Preceded with Tabs.
  private void foo() {}

  /**
    * // violation
  */ // violation
  private Example3() {}

  private enum tabsExample {
    /**
       * Incorrect indentation for leading asterisk. // violation */
    ONE,

    /**
      This javadoc is allowed because there is no leading asterisk.
     */
    TWO
  }
}

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