Class JavadocBlockTagLocationCheck
- 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.javadoc.AbstractJavadocCheck
-
- com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocBlockTagLocationCheck
-
- All Implemented Interfaces:
Configurable
,Contextualizable
public class JavadocBlockTagLocationCheck extends AbstractJavadocCheck
Checks that a javadoc block tag appears only at the beginning of a line, ignoring leading asterisks and white space. A block tag is a token that starts with@
symbol and is preceded by a whitespace. This check ignores block tags in comments and inside inline tags {@code } and {@literal }.Rationale: according to the specification all javadoc block tags should be placed at the beginning of a line. Tags that are not placed at the beginning are treated as plain text. To recognize intentional tag placement to text area it is better to escape the
@
symbol, and all non-escaped tags should be located at the beginning of the line. See NOTE section for details on how to escape.To place a tag explicitly as text, escape the
@
symbol with HTML entity @ or place it inside{@code }
, for example:/** * @serial literal in {@code @serial} Javadoc tag. */
-
Property
tags
- Specify the javadoc tags to process. Type isjava.lang.String[]
. Default value isauthor, deprecated, exception, hidden, param, provides, return, see, serial, serialData, serialField, since, throws, uses, version
. -
Property
violateExecutionOnNonTightHtml
- Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Type isboolean
. Default value isfalse
.
Parent is
com.puppycrawl.tools.checkstyle.TreeWalker
Violation Message Keys:
-
javadoc.blockTagLocation
-
javadoc.missed.html.close
-
javadoc.parse.rule.error
-
javadoc.unclosedHtml
-
javadoc.wrong.singleton.html.tag
- Since:
- 8.24
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
AbstractAutomaticBean.OutputStreamOptions
-
-
Field Summary
Fields Modifier and Type Field Description private static String[]
DEFAULT_TAGS
Block tags from Java 11 Documentation Comment Specification.private static Pattern
JAVADOC_BLOCK_TAG_PATTERN
This regexp is used to extract the javadoc tags.static String
MSG_BLOCK_TAG_LOCATION
A key is pointing to the warning message text in "messages.properties" file.private Set<String>
tags
Specify the javadoc tags to process.-
Fields inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck
MSG_JAVADOC_MISSED_HTML_CLOSE, MSG_JAVADOC_PARSE_RULE_ERROR, MSG_JAVADOC_WRONG_SINGLETON_TAG, MSG_KEY_UNCLOSED_HTML_TAG
-
-
Constructor Summary
Constructors Constructor Description JavadocBlockTagLocationCheck()
Creates a newJavadocBlockTagLocationCheck
instance with default settings.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int[]
getAcceptableJavadocTokens()
The configurable javadoc token set.int[]
getDefaultJavadocTokens()
Returns the default javadoc token types a check is interested in.int[]
getRequiredJavadocTokens()
The javadoc tokens that this check must be registered for.private static boolean
isCommentOrInlineTag(DetailNode node)
Checks if the node can contain an unescaped block tag without violation.void
setTags(String... values)
Setter to specify the javadoc tags to process.void
visitJavadocToken(DetailNode ast)
Called to process a Javadoc token.-
Methods inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck
acceptJavadocWithNonTightHtml, beginJavadocTree, beginTree, destroy, finishJavadocTree, finishTree, getAcceptableTokens, getBlockCommentAst, getDefaultTokens, getRequiredTokens, init, isCommentNodesRequired, leaveJavadocToken, setJavadocTokens, setViolateExecutionOnNonTightHtml, visitToken
-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
clearViolations, getFileContents, getFilePath, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, 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_BLOCK_TAG_LOCATION
public static final String MSG_BLOCK_TAG_LOCATION
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
JAVADOC_BLOCK_TAG_PATTERN
private static final Pattern JAVADOC_BLOCK_TAG_PATTERN
This regexp is used to extract the javadoc tags.
-
DEFAULT_TAGS
private static final String[] DEFAULT_TAGS
Block tags from Java 11 Documentation Comment Specification.
-
-
Constructor Detail
-
JavadocBlockTagLocationCheck
public JavadocBlockTagLocationCheck()
Creates a newJavadocBlockTagLocationCheck
instance with default settings.
-
-
Method Detail
-
setTags
public final void setTags(String... values)
Setter to specify the javadoc tags to process.- Parameters:
values
- user's values.- Since:
- 8.24
-
getRequiredJavadocTokens
public int[] getRequiredJavadocTokens()
The javadoc tokens that this check must be registered for. According to the specs each block tag must appear at the beginning of a line, otherwise it will be interpreted as a plain text. This check looks for a block tag in the javadoc text, thus it needs theTEXT
tokens.- Overrides:
getRequiredJavadocTokens
in classAbstractJavadocCheck
- Returns:
- the javadoc token set this must be registered for.
- See Also:
JavadocTokenTypes
-
getAcceptableJavadocTokens
public int[] getAcceptableJavadocTokens()
Description copied from class:AbstractJavadocCheck
The configurable javadoc token set. Used to protect Checks against malicious users who specify an unacceptable javadoc token set in the configuration file. The default implementation returns the check's default javadoc tokens.- Overrides:
getAcceptableJavadocTokens
in classAbstractJavadocCheck
- Returns:
- the javadoc token set this check is designed for.
- See Also:
JavadocTokenTypes
-
getDefaultJavadocTokens
public int[] getDefaultJavadocTokens()
Description copied from class:AbstractJavadocCheck
Returns the default javadoc token types a check is interested in.- Specified by:
getDefaultJavadocTokens
in classAbstractJavadocCheck
- Returns:
- the default javadoc token types
- See Also:
JavadocTokenTypes
-
visitJavadocToken
public void visitJavadocToken(DetailNode ast)
Description copied from class:AbstractJavadocCheck
Called to process a Javadoc token.- Specified by:
visitJavadocToken
in classAbstractJavadocCheck
- Parameters:
ast
- the token to process
-
isCommentOrInlineTag
private static boolean isCommentOrInlineTag(DetailNode node)
Checks if the node can contain an unescaped block tag without violation.- Parameters:
node
- to check- Returns:
true
if node is@code
,@literal
or HTML comment.
-
-