Class CommentsIndentationCheck
- java.lang.Object
-
- com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
-
- com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
-
- com.puppycrawl.tools.checkstyle.api.AbstractCheck
-
- com.puppycrawl.tools.checkstyle.checks.indentation.CommentsIndentationCheck
-
- All Implemented Interfaces:
Configurable
,Contextualizable
public class CommentsIndentationCheck extends AbstractCheck
Controls the indentation between comments and surrounding code. Comments are indented at the same level as the surrounding code. Detailed info about such convention can be found here-
Property
tokens
- tokens to check Type isjava.lang.String[]
. Validation type istokenSet
. Default value is: SINGLE_LINE_COMMENT, BLOCK_COMMENT_BEGIN.
Parent is
com.puppycrawl.tools.checkstyle.TreeWalker
Violation Message Keys:
-
comments.indentation.block
-
comments.indentation.single
- Since:
- 6.10
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
AbstractAutomaticBean.OutputStreamOptions
-
-
Field Summary
Fields Modifier and Type Field Description static String
MSG_KEY_BLOCK
A key is pointing to the warning message text in "messages.properties" file.static String
MSG_KEY_SINGLE
A key is pointing to the warning message text in "messages.properties" file.
-
Constructor Summary
Constructors Constructor Description CommentsIndentationCheck()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private static boolean
areInSameMethodCallWithSameIndent(DetailAST comment)
Checks if the comment is inside a method call with same indentation of first expression. e.g:private boolean
areSameLevelIndented(DetailAST comment, DetailAST prevStmt, DetailAST nextStmt)
Checks if comment and next code statement (or previous code stmt like case in switch block) are indented at the same level, e.g.:private int
countEmptyLines(DetailAST startStatement, DetailAST endStatement)
Count the number of empty lines between statements.private DetailAST
findPreviousStatement(DetailAST comment, DetailAST root)
Finds a previous statement of the comment.private static DetailAST
findStartTokenOfMethodCallChain(DetailAST root)
Finds the start token of method call chain.private static DetailAST
findTokenWhichBeginsTheLine(DetailAST root)
Finds a token which begins the line.int[]
getAcceptableTokens()
The configurable token set.int[]
getDefaultTokens()
Returns the default token a check is interested in.private static DetailAST
getDistributedPreviousStatement(DetailAST comment)
Returns the first token of the distributed previous statement of comment.private static DetailAST
getFirstExpressionNodeFromMethodCall(DetailAST methodCall)
Returns the first EXPR DetailAST child from parent of comment.private int
getLineStart(int lineNo)
Get a column number where a code starts.private static String
getMessageKey(DetailAST comment)
Get a message key depending on a comment type.private static DetailAST
getNextStmt(DetailAST comment)
Returns the next statement of a comment.private DetailAST
getNextToken(DetailAST checkedStatement)
Get the token to start counting the number of lines to add to the distance aim from.private DetailAST
getOneLinePreviousStatement(DetailAST comment)
Does pre-order traverse of abstract syntax tree to find the previous statement of the comment.private static DetailAST
getPrevCaseToken(DetailAST parentStatement)
Gets previous case-token for comment.private DetailAST
getPreviousStatement(DetailAST comment)
Returns the previous statement of a comment.private static DetailAST
getPrevStatementFromSwitchBlock(DetailAST comment)
Gets comment's previous statement from switch block.private static DetailAST
getPrevStatementWhenCommentIsUnderCase(DetailAST parentStatement)
Gets previous statement for comment which is placed immediately under case.int[]
getRequiredTokens()
The tokens that this check must be registered for.private void
handleCommentAtTheEndOfTheCodeBlock(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed at the end of non-empty code block.private void
handleCommentInEmptyCaseBlock(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed within empty case block.private void
handleCommentInEmptyCodeBlock(DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed within the empty code block.private void
handleFallThroughComment(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles 'fall through' single-line comment.private static boolean
isBlockStart(DetailAST root)
Whether the AST node starts a block.private static boolean
isComment(DetailAST ast)
Whether the ast is a comment.private static boolean
isCommentAtTheEndOfTheCodeBlock(DetailAST nextStmt)
Checks whether a comment is placed at the end of the code block.private static boolean
isCommentForMultiblock(DetailAST endBlockStmt)
Whether the comment might have been used for the next block in a multi-block structure.boolean
isCommentNodesRequired()
Whether comment nodes are required or not.private static boolean
isDefinition(DetailAST previousSibling)
Whether the statement is a kind of definition (method, class etc.).private boolean
isDistributedExpression(DetailAST comment)
Checks whether the previous statement of a comment is a method call chain or string concatenation statement distributed over two or more lines.private boolean
isDistributedPreviousStatement(DetailAST comment)
Checks whether the previous statement of a comment is distributed over two or more lines.private static boolean
isDistributedReturnStatement(DetailAST commentPreviousSibling)
Checks whether the previous statement of a comment is a distributed return statement.private static boolean
isDistributedThrowStatement(DetailAST commentPreviousSibling)
Checks whether the previous statement of a comment is a distributed throw statement.private static boolean
isFallThroughComment(DetailAST prevStmt, DetailAST nextStmt)
Checks whether comment is a 'fall through' comment.private static boolean
isInEmptyCaseBlock(DetailAST prevStmt, DetailAST nextStmt)
Checks whether case block is empty.private static boolean
isInEmptyCodeBlock(DetailAST prevStmt, DetailAST nextStmt)
Checks whether comment is placed in the empty code block.private boolean
isOnPreviousLineIgnoringComments(DetailAST currentStatement, DetailAST checkedStatement)
Checks whether the checked statement is on the previous line ignoring empty lines and lines which contain only comments.private static boolean
isStatementWithPossibleCurlies(DetailAST previousSibling)
Whether the statement can have or always have curly brackets.private boolean
isTrailingBlockComment(DetailAST blockComment)
Checks if current comment block is trailing comment, e.g.:private boolean
isTrailingComment(DetailAST comment)
Checks if current comment is a trailing comment.private boolean
isTrailingSingleLineComment(DetailAST singleLineComment)
Checks if current single-line comment is trailing comment, e.g.:private static boolean
isUsingOfObjectReferenceToInvokeMethod(DetailAST root)
Checks whether there is a use of an object reference to invoke an object's method on line.private void
logMultilineIndentation(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Logs comment which can have the same indentation level as next or previous statement.private void
visitComment(DetailAST comment)
Checks comment indentations over surrounding code, e.g.:void
visitToken(DetailAST commentAst)
Called to process a token.-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
beginTree, clearViolations, destroy, finishTree, getFileContents, getFilePath, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, init, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens
-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity
-
Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
configure, contextualize, getConfiguration, setupChild
-
-
-
-
Field Detail
-
MSG_KEY_SINGLE
public static final String MSG_KEY_SINGLE
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_KEY_BLOCK
public static final String MSG_KEY_BLOCK
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
CommentsIndentationCheck
public CommentsIndentationCheck()
-
-
Method Detail
-
getDefaultTokens
public int[] getDefaultTokens()
Description copied from class:AbstractCheck
Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.- Specified by:
getDefaultTokens
in classAbstractCheck
- Returns:
- the default tokens
- See Also:
TokenTypes
-
getAcceptableTokens
public int[] getAcceptableTokens()
Description copied from class:AbstractCheck
The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.- Specified by:
getAcceptableTokens
in classAbstractCheck
- Returns:
- the token set this check is designed for.
- See Also:
TokenTypes
-
getRequiredTokens
public int[] getRequiredTokens()
Description copied from class:AbstractCheck
The tokens that this check must be registered for.- Specified by:
getRequiredTokens
in classAbstractCheck
- Returns:
- the token set this must be registered for.
- See Also:
TokenTypes
-
isCommentNodesRequired
public boolean isCommentNodesRequired()
Description copied from class:AbstractCheck
Whether comment nodes are required or not.- Overrides:
isCommentNodesRequired
in classAbstractCheck
- Returns:
- false as a default value.
-
visitToken
public void visitToken(DetailAST commentAst)
Description copied from class:AbstractCheck
Called to process a token.- Overrides:
visitToken
in classAbstractCheck
- Parameters:
commentAst
- the token to process
-
visitComment
private void visitComment(DetailAST comment)
Checks comment indentations over surrounding code, e.g.:// some comment - this is ok double d = 3.14; // some comment - this is <b>not</b> ok. double d1 = 5.0;
- Parameters:
comment
- comment to check.
-
getNextStmt
private static DetailAST getNextStmt(DetailAST comment)
Returns the next statement of a comment.- Parameters:
comment
- comment.- Returns:
- the next statement of a comment.
-
getPreviousStatement
private DetailAST getPreviousStatement(DetailAST comment)
Returns the previous statement of a comment.- Parameters:
comment
- comment.- Returns:
- the previous statement of a comment.
-
isDistributedPreviousStatement
private boolean isDistributedPreviousStatement(DetailAST comment)
Checks whether the previous statement of a comment is distributed over two or more lines.- Parameters:
comment
- comment to check.- Returns:
- true if the previous statement of a comment is distributed over two or more lines.
-
isDistributedExpression
private boolean isDistributedExpression(DetailAST comment)
Checks whether the previous statement of a comment is a method call chain or string concatenation statement distributed over two or more lines.- Parameters:
comment
- comment to check.- Returns:
- true if the previous statement is a distributed expression.
-
isStatementWithPossibleCurlies
private static boolean isStatementWithPossibleCurlies(DetailAST previousSibling)
Whether the statement can have or always have curly brackets.- Parameters:
previousSibling
- the statement to check.- Returns:
- true if the statement can have or always have curly brackets.
-
isDefinition
private static boolean isDefinition(DetailAST previousSibling)
Whether the statement is a kind of definition (method, class etc.).- Parameters:
previousSibling
- the statement to check.- Returns:
- true if the statement is a kind of definition.
-
isDistributedReturnStatement
private static boolean isDistributedReturnStatement(DetailAST commentPreviousSibling)
Checks whether the previous statement of a comment is a distributed return statement.- Parameters:
commentPreviousSibling
- previous sibling of the comment.- Returns:
- true if the previous statement of a comment is a distributed return statement.
-
isDistributedThrowStatement
private static boolean isDistributedThrowStatement(DetailAST commentPreviousSibling)
Checks whether the previous statement of a comment is a distributed throw statement.- Parameters:
commentPreviousSibling
- previous sibling of the comment.- Returns:
- true if the previous statement of a comment is a distributed throw statement.
-
getDistributedPreviousStatement
private static DetailAST getDistributedPreviousStatement(DetailAST comment)
Returns the first token of the distributed previous statement of comment.- Parameters:
comment
- comment to check.- Returns:
- the first token of the distributed previous statement of comment.
-
isInEmptyCaseBlock
private static boolean isInEmptyCaseBlock(DetailAST prevStmt, DetailAST nextStmt)
Checks whether case block is empty.- Parameters:
prevStmt
- next statement.nextStmt
- previous statement.- Returns:
- true if case block is empty.
-
isFallThroughComment
private static boolean isFallThroughComment(DetailAST prevStmt, DetailAST nextStmt)
Checks whether comment is a 'fall through' comment. For example:... case OPTION_ONE: int someVariable = 1; // fall through case OPTION_TWO: int a = 5; break; ...
- Parameters:
prevStmt
- previous statement.nextStmt
- next statement.- Returns:
- true if a comment is a 'fall through' comment.
-
isCommentAtTheEndOfTheCodeBlock
private static boolean isCommentAtTheEndOfTheCodeBlock(DetailAST nextStmt)
Checks whether a comment is placed at the end of the code block.- Parameters:
nextStmt
- next statement.- Returns:
- true if a comment is placed at the end of the block.
-
isInEmptyCodeBlock
private static boolean isInEmptyCodeBlock(DetailAST prevStmt, DetailAST nextStmt)
Checks whether comment is placed in the empty code block. For example:...
Note, the method does not treat empty case blocks.// empty code block
...- Parameters:
prevStmt
- previous statement.nextStmt
- next statement.- Returns:
- true if comment is placed in the empty code block.
-
handleCommentInEmptyCaseBlock
private void handleCommentInEmptyCaseBlock(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed within empty case block. Note, if comment is placed at the end of the empty case block, we have Checkstyle's limitations to clearly detect user intention of explanation target - above or below. The only case we can assume as a violation is when a single-line comment within the empty case block has indentation level that is lower than the indentation level of the next case token. For example:... case OPTION_ONE: // violation case OPTION_TWO: ...
- Parameters:
prevStmt
- previous statement.comment
- single-line comment.nextStmt
- next statement.
-
handleFallThroughComment
private void handleFallThroughComment(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles 'fall through' single-line comment. Note, 'fall through' and similar comments can have indentation level as next or previous statement. For example:... case OPTION_ONE: int someVariable = 1; // fall through - OK case OPTION_TWO: int a = 5; break; ...
... case OPTION_ONE: int someVariable = 1; // then init variable a - OK case OPTION_TWO: int a = 5; break; ...
- Parameters:
prevStmt
- previous statement.comment
- single-line comment.nextStmt
- next statement.
-
handleCommentAtTheEndOfTheCodeBlock
private void handleCommentAtTheEndOfTheCodeBlock(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed at the end of non-empty code block. Note, if single-line comment is placed at the end of non-empty block the comment should have the same indentation level as the previous statement. For example:if (a == true) { int b = 1; // comment }
- Parameters:
prevStmt
- previous statement.comment
- comment to check.nextStmt
- next statement.
-
isCommentForMultiblock
private static boolean isCommentForMultiblock(DetailAST endBlockStmt)
Whether the comment might have been used for the next block in a multi-block structure.- Parameters:
endBlockStmt
- the end of the current block.- Returns:
- true, if the comment might have been used for the next block in a multi-block structure.
-
handleCommentInEmptyCodeBlock
private void handleCommentInEmptyCodeBlock(DetailAST comment, DetailAST nextStmt)
Handles a comment which is placed within the empty code block. Note, if comment is placed at the end of the empty code block, we have Checkstyle's limitations to clearly detect user intention of explanation target - above or below. The only case we can assume as a violation is when a single-line comment within the empty code block has indentation level that is lower than the indentation level of the closing right curly brace. For example:if (a == true) { // violation }
- Parameters:
comment
- comment to check.nextStmt
- next statement.
-
getOneLinePreviousStatement
private DetailAST getOneLinePreviousStatement(DetailAST comment)
Does pre-order traverse of abstract syntax tree to find the previous statement of the comment. If previous statement of the comment is found, then the traverse will be finished.- Parameters:
comment
- current statement.- Returns:
- previous statement of the comment or null if the comment does not have previous statement.
-
isComment
private static boolean isComment(DetailAST ast)
Whether the ast is a comment.- Parameters:
ast
- the ast to check.- Returns:
- true if the ast is a comment.
-
isBlockStart
private static boolean isBlockStart(DetailAST root)
Whether the AST node starts a block.- Parameters:
root
- the AST node to check.- Returns:
- true if the AST node starts a block.
-
findPreviousStatement
private DetailAST findPreviousStatement(DetailAST comment, DetailAST root)
Finds a previous statement of the comment. Uses root token of the line while searching.- Parameters:
comment
- comment.root
- root token of the line.- Returns:
- previous statement of the comment or null if previous statement was not found.
-
findTokenWhichBeginsTheLine
private static DetailAST findTokenWhichBeginsTheLine(DetailAST root)
Finds a token which begins the line.- Parameters:
root
- root token of the line.- Returns:
- token which begins the line.
-
isUsingOfObjectReferenceToInvokeMethod
private static boolean isUsingOfObjectReferenceToInvokeMethod(DetailAST root)
Checks whether there is a use of an object reference to invoke an object's method on line.- Parameters:
root
- root token of the line.- Returns:
- true if there is a use of an object reference to invoke an object's method on line.
-
findStartTokenOfMethodCallChain
private static DetailAST findStartTokenOfMethodCallChain(DetailAST root)
Finds the start token of method call chain.- Parameters:
root
- root token of the line.- Returns:
- the start token of method call chain.
-
isOnPreviousLineIgnoringComments
private boolean isOnPreviousLineIgnoringComments(DetailAST currentStatement, DetailAST checkedStatement)
Checks whether the checked statement is on the previous line ignoring empty lines and lines which contain only comments.- Parameters:
currentStatement
- current statement.checkedStatement
- checked statement.- Returns:
- true if checked statement is on the line which is previous to current statement ignoring empty lines and lines which contain only comments.
-
getNextToken
private DetailAST getNextToken(DetailAST checkedStatement)
Get the token to start counting the number of lines to add to the distance aim from.- Parameters:
checkedStatement
- the checked statement.- Returns:
- the token to start counting the number of lines to add to the distance aim from.
-
countEmptyLines
private int countEmptyLines(DetailAST startStatement, DetailAST endStatement)
Count the number of empty lines between statements.- Parameters:
startStatement
- start statement.endStatement
- end statement.- Returns:
- the number of empty lines between statements.
-
logMultilineIndentation
private void logMultilineIndentation(DetailAST prevStmt, DetailAST comment, DetailAST nextStmt)
Logs comment which can have the same indentation level as next or previous statement.- Parameters:
prevStmt
- previous statement.comment
- comment.nextStmt
- next statement.
-
getMessageKey
private static String getMessageKey(DetailAST comment)
Get a message key depending on a comment type.- Parameters:
comment
- the comment to process.- Returns:
- a message key.
-
getPrevStatementFromSwitchBlock
private static DetailAST getPrevStatementFromSwitchBlock(DetailAST comment)
Gets comment's previous statement from switch block.- Parameters:
comment
-single-line comment
.- Returns:
- comment's previous statement or null if previous statement is absent.
-
getPrevStatementWhenCommentIsUnderCase
private static DetailAST getPrevStatementWhenCommentIsUnderCase(DetailAST parentStatement)
Gets previous statement for comment which is placed immediately under case.- Parameters:
parentStatement
- comment's parent statement.- Returns:
- comment's previous statement or null if previous statement is absent.
-
getPrevCaseToken
private static DetailAST getPrevCaseToken(DetailAST parentStatement)
Gets previous case-token for comment.- Parameters:
parentStatement
- comment's parent statement.- Returns:
- previous case-token or null if previous case-token is absent.
-
areSameLevelIndented
private boolean areSameLevelIndented(DetailAST comment, DetailAST prevStmt, DetailAST nextStmt)
Checks if comment and next code statement (or previous code stmt like case in switch block) are indented at the same level, e.g.:// some comment - same indentation level int x = 10; // some comment - different indentation level int x1 = 5; /* * */ boolean bool = true; - same indentation level
- Parameters:
comment
-single-line comment
.prevStmt
- previous code statement.nextStmt
- next code statement.- Returns:
- true if comment and next code statement are indented at the same level.
-
getLineStart
private int getLineStart(int lineNo)
Get a column number where a code starts.- Parameters:
lineNo
- the line number to get column number in.- Returns:
- the column number where a code starts.
-
isTrailingComment
private boolean isTrailingComment(DetailAST comment)
Checks if current comment is a trailing comment.- Parameters:
comment
- comment to check.- Returns:
- true if current comment is a trailing comment.
-
isTrailingSingleLineComment
private boolean isTrailingSingleLineComment(DetailAST singleLineComment)
Checks if current single-line comment is trailing comment, e.g.:double d = 3.14; // some comment
- Parameters:
singleLineComment
-single-line comment
.- Returns:
- true if current single-line comment is trailing comment.
-
isTrailingBlockComment
private boolean isTrailingBlockComment(DetailAST blockComment)
Checks if current comment block is trailing comment, e.g.:double d = 3.14; /* some comment */ /* some comment */ double d = 18.5;
- Parameters:
blockComment
-block comment begin
.- Returns:
- true if current comment block is trailing comment.
-
areInSameMethodCallWithSameIndent
private static boolean areInSameMethodCallWithSameIndent(DetailAST comment)
Checks if the comment is inside a method call with same indentation of first expression. e.g:private final boolean myList = someMethod( // Some comment here s1, s2, s3 // ok );
- Parameters:
comment
- comment to check.- Returns:
- true, if comment is inside a method call with same indentation.
-
getFirstExpressionNodeFromMethodCall
private static DetailAST getFirstExpressionNodeFromMethodCall(DetailAST methodCall)
Returns the first EXPR DetailAST child from parent of comment.- Parameters:
methodCall
- methodCall DetailAst from which node to be extracted.- Returns:
- first EXPR DetailAST child from parent of comment.
-
-