Package com.puppycrawl.tools.checkstyle.checks.javadoc

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 is java.lang.String[]. Default value is author, 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 is boolean. Default value is false.

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 final String[]	DEFAULT_TAGS	Block tags from Java 11 Documentation Comment Specification.
private static final Pattern	JAVADOC_BLOCK_TAG_PATTERN	This regexp is used to extract the javadoc tags.
static final 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 new JavadocBlockTagLocationCheck instance with default settings.

Method Summary

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.
final 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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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.

tags

private Set<String> tags

Specify the javadoc tags to process.

Constructor Details

JavadocBlockTagLocationCheck

public JavadocBlockTagLocationCheck()

Creates a new JavadocBlockTagLocationCheck instance with default settings.

Method Details

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 the TEXT tokens.

Overrides:

getRequiredJavadocTokens in class AbstractJavadocCheck

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 class AbstractJavadocCheck

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 class AbstractJavadocCheck

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 class AbstractJavadocCheck

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.