Class 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
  • 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:
    • DOT

      private static final char DOT
      Dot.
      See Also:
    • 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:
    • 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:
    • 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:
    • 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