Class JavadocBlockTagLocationCheck
- All Implemented Interfaces:
Configurable
,Contextualizable
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
.
To configure the default check:
<module name="JavadocBlockTagLocation"/>
Example:
/** * Escaped tag @version (OK) * Plain text with {@code @see} (OK) * A @custom tag (OK) * * email@author (OK) * (@param in parentheses) (OK) * '@param in single quotes' (OK) * @since 1.0 (OK) * text @return (violation) * * @param (violation) +* @serial (violation) * @see first (OK) @see second (violation) */ public int field;
To configure the check to verify tags from JEP 8068562 only:
<module name="JavadocBlockTagLocation"> <property name="tags" value="apiNote, implSpec, implNote"/> </module>
To configure the check to verify all default tags and some custom tags in addition:
<module name="JavadocBlockTagLocation"> <!-- default tags --> <property name="tags" value="author, deprecated, exception, hidden"/> <property name="tags" value="param, provides, return, see, serial"/> <property name="tags" value="serialData, serialField, since, throws"/> <property name="tags" value="uses, version"/> <!-- additional tags used in the project --> <property name="tags" value="noinspection"/> </module>
Parent is com.puppycrawl.tools.checkstyle.TreeWalker
Violation Message Keys:
-
javadoc.blockTagLocation
-
javadoc.missed.html.close
-
javadoc.parse.rule.error
-
javadoc.wrong.singleton.html.tag
- Since:
- 8.24
-
Nested Class Summary
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
AutomaticBean.OutputStreamOptions
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
A key is pointing to the warning message text in "messages.properties" file.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
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a newJavadocBlockTagLocationCheck
instance with default settings. -
Method Summary
Modifier and TypeMethodDescriptionint[]
The configurable javadoc token set.int[]
Returns the default javadoc token types a check is interested in.int[]
The javadoc tokens that this check must be registered for.final void
Setter to specify the javadoc tags to process.void
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
clearMessages, getFileContents, getLine, getLines, getMessages, getTabWidth, getTokenNames, 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.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Field Details
-
MSG_BLOCK_TAG_LOCATION
A key is pointing to the warning message text in "messages.properties" file.- See Also:
-
-
Constructor Details
-
JavadocBlockTagLocationCheck
public JavadocBlockTagLocationCheck()Creates a newJavadocBlockTagLocationCheck
instance with default settings.
-
-
Method Details
-
setTags
Setter to specify the javadoc tags to process.- Parameters:
values
- user's values.
-
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:
-
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:
-
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:
-
visitJavadocToken
Description copied from class:AbstractJavadocCheck
Called to process a Javadoc token.- Specified by:
visitJavadocToken
in classAbstractJavadocCheck
- Parameters:
ast
- the token to process
-