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

Class JavadocLinkFirstOccurrenceCheck

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

All Implemented Interfaces:

Configurable, Contextualizable

public class JavadocLinkFirstOccurrenceCheck
extends AbstractJavadocCheck

Checks that in Javadoc comments, each API name is linked with {@link} or {@linkplain} only on its first occurrence. Subsequent links to the same API name in the same comment are flagged.

Rationale: From the Documentation Comments style guide, links call attention to themselves by their color and underline in HTML, and by their length in source code doc comments. Linking the same name multiple times is redundant.

Two links are considered to reference the same API name if they resolve to the same canonical name. Simple names are resolved through explicit imports, types declared in the current file, star imports and the java.lang package. Names containing dots are resolved through imports of their outermost segment; otherwise they are compared as written.

Since:

14.1.0

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 Set<String>	declaredTypeNames	Set of simple names of types declared in the current file.
private static final char	DOT	Dot.
private Map<String,String>	importedNames	Map of imported simple names to fully qualified names.
private final Set<String>	linkedNames	Set of reference keys already seen in the current Javadoc comment.
static final String	MSG_KEY	A key is pointing to the warning message text in "messages.properties" file.
private Set<String>	starImports	Set of star import base packages.
private static final Set<Integer>	TYPE_DECLARATION_TOKENS	Tokens of type declarations.

Fields inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

MSG_JAVADOC_PARSE_RULE_ERROR, MSG_KEY_UNCLOSED_HTML_TAG

Constructor Summary

Constructors

Constructor	Description
JavadocLinkFirstOccurrenceCheck()	Creates a new JavadocLinkFirstOccurrenceCheck instance.

Method Summary

Modifier and Type	Method	Description
void	beginJavadocTree(DetailNode rootAst)	Called before the starting to process a tree.
void	beginTree(DetailAST rootAST)	Called before the starting to process a tree.
private void	collectDeclaredTypeNames(DetailAST rootAST)	Records the simple names of all type declarations.
int[]	getDefaultJavadocTokens()	Returns the default javadoc token types a check is interested in.
private static String	getNodeText(DetailNode node)	Recursively builds the full text of a node by concatenating the text of all its leaf descendants.
int[]	getRequiredJavadocTokens()	The javadoc tokens that this check must be registered for.
int[]	getRequiredTokens()	The tokens that this check must be registered for.
private void	handleImport(DetailAST ast)	Processes import statements and records imported names.
private String	resolveClass(String name)	Resolves a class name to its canonical name through imports, types declared in the current file, star imports and the java.lang package.
private String	resolveOuterSegment(String name, int dotIndex)	Resolves the outermost segment of a dotted class name through imports, keeping the remainder unchanged.
private String	resolveReference(String reference)	Resolves a reference text to a canonical key for identity comparison.
private String	resolveSimpleClassName(String name)	Resolves a simple class name through imports, types declared in the current file, star imports and the java.lang package.
void	visitJavadocToken(DetailNode ast)	Called to process a Javadoc token.
void	visitToken(DetailAST ast)	Called to process a token.

Methods inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

acceptJavadocWithNonTightHtml, destroy, finishJavadocTree, getAcceptableJavadocTokens, getAcceptableTokens, getBlockCommentAst, getDefaultTokens, init, isCommentNodesRequired, leaveJavadocToken, log, setJavadocTokens, setViolateExecutionOnNonTightHtml

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

clearViolations, finishTree, 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_KEY

public static final String MSG_KEY

A key is pointing to the warning message text in "messages.properties" file.

See Also:

• Constant Field Values

DOT

private static final char DOT

Dot.

See Also:

• Constant Field Values

TYPE_DECLARATION_TOKENS

private static final Set<Integer> TYPE_DECLARATION_TOKENS

Tokens of type declarations.

linkedNames

private final Set<String> linkedNames

Set of reference keys already seen in the current Javadoc comment.

importedNames

private Map<String,String> importedNames

Map of imported simple names to fully qualified names.

starImports

private Set<String> starImports

Set of star import base packages.

declaredTypeNames

private Set<String> declaredTypeNames

Set of simple names of types declared in the current file.

Constructor Details

JavadocLinkFirstOccurrenceCheck

public JavadocLinkFirstOccurrenceCheck()

Creates a new JavadocLinkFirstOccurrenceCheck instance.

Method Details

getRequiredTokens

public int[] getRequiredTokens()

Description copied from class: AbstractCheck

The tokens that this check must be registered for.

Overrides:

getRequiredTokens in class AbstractJavadocCheck

Returns:

the token set this must be registered for.

See Also:

• TokenTypes

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:

• JavadocCommentsTokenTypes

getRequiredJavadocTokens

public int[] getRequiredJavadocTokens()

Description copied from class: AbstractJavadocCheck

The javadoc tokens that this check must be registered for.

Overrides:

getRequiredJavadocTokens in class AbstractJavadocCheck

Returns:

the javadoc token set this must be registered for.

See Also:

• JavadocCommentsTokenTypes

beginTree

public void beginTree(DetailAST rootAST)

Description copied from class: AbstractCheck

Called before the starting to process a tree. Ideal place to initialize information that is to be collected whilst processing a tree.

Overrides:

beginTree in class AbstractJavadocCheck

Parameters:

rootAST - the root of the tree

beginJavadocTree

public void beginJavadocTree(DetailNode rootAst)

Description copied from class: AbstractJavadocCheck

Called before the starting to process a tree.

Overrides:

beginJavadocTree in class AbstractJavadocCheck

Parameters:

rootAst - the root of the tree

visitToken

public void visitToken(DetailAST ast)

Description copied from class: AbstractCheck

Called to process a token.

Overrides:

visitToken in class AbstractJavadocCheck

Parameters:

ast - the token to process

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

handleImport

private void handleImport(DetailAST ast)

Processes import statements and records imported names.

Parameters:

ast - import node

collectDeclaredTypeNames

private void collectDeclaredTypeNames(DetailAST rootAST)

Records the simple names of all type declarations. The whole tree is scanned so that types declared after their references are also taken into account.

Parameters:

rootAST - the root of the tree to scan

resolveReference

private String resolveReference(String reference)

Resolves a reference text to a canonical key for identity comparison. The class part of the reference is resolved through imports and types declared in the current file.

Parameters:

reference - the raw reference text

Returns:

the resolved identity key

resolveClass

private String resolveClass(String name)

Resolves a class name to its canonical name through imports, types declared in the current file, star imports and the java.lang package. Names containing dots have only their outermost segment resolved; otherwise they are returned unchanged.

Parameters:

name - the class name

Returns:

the resolved canonical name

resolveSimpleClassName

private String resolveSimpleClassName(String name)

Resolves a simple class name through imports, types declared in the current file, star imports and the java.lang package.

Parameters:

name - the simple class name

Returns:

the resolved canonical name

resolveOuterSegment

private String resolveOuterSegment(String name,
 int dotIndex)

Resolves the outermost segment of a dotted class name through imports, keeping the remainder unchanged.

Parameters:

name - the dotted class name

dotIndex - the index of the first dot in the name

Returns:

the resolved canonical name

getNodeText

private static String getNodeText(DetailNode node)

Recursively builds the full text of a node by concatenating the text of all its leaf descendants.

Parameters:

node - the node to get text from

Returns:

the concatenated text, or null if the node is null