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.
*/
tags - Specify the javadoc tags to process.
Type is java.lang.String[].
Default value is author, deprecated, exception, hidden, param, provides,
return, see, serial, serialData, serialField, since, throws, uses, version.
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 is boolean.
Default value is false.
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
AutomaticBean.OutputStreamOptions| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
MSG_BLOCK_TAG_LOCATION
A key is pointing to the warning message text in "messages.properties" file.
|
MSG_JAVADOC_MISSED_HTML_CLOSE, MSG_JAVADOC_PARSE_RULE_ERROR, MSG_JAVADOC_WRONG_SINGLETON_TAG| Constructor and Description |
|---|
JavadocBlockTagLocationCheck()
Creates a new
JavadocBlockTagLocationCheck instance with default settings. |
| Modifier and Type | Method and 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.
|
void |
setTags(java.lang.String... values)
Setter to specify the javadoc tags to process.
|
void |
visitJavadocToken(DetailNode ast)
Called to process a Javadoc token.
|
acceptJavadocWithNonTightHtml, beginJavadocTree, beginTree, destroy, finishJavadocTree, finishTree, getAcceptableTokens, getBlockCommentAst, getDefaultTokens, getRequiredTokens, init, isCommentNodesRequired, leaveJavadocToken, setJavadocTokens, setViolateExecutionOnNonTightHtml, visitTokenclearMessages, getFileContents, getLine, getLines, getMessages, getTabWidth, getTokenNames, leaveToken, log, log, log, setFileContents, setTabWidth, setTokensfinishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverityconfigure, contextualize, getConfiguration, setupChildpublic static final java.lang.String MSG_BLOCK_TAG_LOCATION
public JavadocBlockTagLocationCheck()
JavadocBlockTagLocationCheck instance with default settings.public final void setTags(java.lang.String... values)
values - user's values.public int[] getRequiredJavadocTokens()
TEXT tokens.getRequiredJavadocTokens in class AbstractJavadocCheckJavadocTokenTypespublic int[] getAcceptableJavadocTokens()
AbstractJavadocCheckgetAcceptableJavadocTokens in class AbstractJavadocCheckJavadocTokenTypespublic int[] getDefaultJavadocTokens()
AbstractJavadocCheckgetDefaultJavadocTokens in class AbstractJavadocCheckJavadocTokenTypespublic void visitJavadocToken(DetailNode ast)
AbstractJavadocCheckvisitJavadocToken in class AbstractJavadocCheckast - the token to processCopyright © 2001-2020. All Rights Reserved.