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 at the number of columns to the right of the slash ( / ) of the opening Javadoc tag specified by the
indentation property. By default they are aligned 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 the opening Javadoc tag line contains leading asterisks, then that line defines the expected alignment and the indentation property is not applied. If you're using tabs then specify the the tab width in the tabWidth property.
Properties
| name | description | type | default value | since |
|---|---|---|---|---|
| indentation | Specify the number of columns to the right of the slash ( / ) of the opening javadoc tag at which the leading asterisks are expected. A negative value expects the leading asterisks to the left of the slash ( / ). | int | 1 |
14.4.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 |
10.18.0 |
Examples
To configure the check:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocLeadingAsteriskAlign" />
</module>
</module>
Example:
// violation 2 lines below '0, expected is 1.'
/**
* Javadoc for class.
*/
public class Example1 {
// violation 2 lines below '2, expected is 1.'
/**
* Javadoc for instance variable, over-indented.
*/
private int wrongIndentField;
/**
* Javadoc for instance variable, correctly aligned.
*/
private int goodIndentField;
// violation 2 lines below '0, expected is 1.'
/**
* Javadoc for method, under-indented.
*/
private void wrongIndentMethod() {}
// violation 2 lines above '0, expected is 1.'
/**
* Javadoc for method, correctly aligned.
*/
private void goodIndentMethod() {}
// violation 3 lines below '-2, expected is 1.'
/**
Javadoc for constructor, missing leading asterisk alignment on closing tag.
*/
private Example1() {}
/**
* Javadoc for constructor, correctly aligned.
*/
public Example1(int value) {}
private enum indentedEnum {
// violation 2 lines below '0, expected is 1.'
/**
* Wrong alignment for enum constant.
*/
WRONG,
/**
* Correct alignment for enum constant.
*/
GOOD
}
}
To configure the check to align leading asterisks under the slash ( / ) of the opening javadoc tag:
<module name="Checker">
<module name="TreeWalker">
<module name="JavadocLeadingAsteriskAlign">
<property name="indentation" value="0"/>
</module>
</module>
</module>
Example:
/**
* Javadoc for class.
*/ // violation '1, expected is 0.'
public class Example2 {
/**
* Javadoc for instance variable, over-indented. // violation '2, expected is 0.'
*/ // violation '1, expected is 0.'
private int wrongIndentField;
/**
* Javadoc for instance variable, correctly aligned. // violation '1, expected is 0.'
*/ // violation '1, expected is 0.'
private int goodIndentField;
/**
* Javadoc for method, under-indented.
*/
private void wrongIndentMethod() {}
/**
* Javadoc for method, correctly aligned. // violation '1, expected is 0.'
*/ // violation '1, expected is 0.'
private void goodIndentMethod() {}
/**
Javadoc for constructor, missing leading asterisk alignment on closing tag.
*/ // violation '-2, expected is 0.'
private Example2() {}
/**
* Javadoc for constructor, correctly aligned. // violation '1, expected is 0.'
*/ // violation '1, expected is 0.'
public Example2(int value) {}
private enum indentedEnum {
/**
* Wrong alignment for enum constant.
*/ // violation '1, expected is 0.'
WRONG,
/**
* Correct alignment for enum constant. // violation '1, expected is 0.'
*/ // violation '1, expected is 0.'
GOOD
}
}
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.JavadocLeadingAsteriskAlignCheck
Use this fully qualified class name in configuration when an exact class reference is required.