Class JavadocLinkWellKnownApiCheck

All Implemented Interfaces:
Configurable, Contextualizable

public class JavadocLinkWellKnownApiCheck extends AbstractJavadocCheck
Checks that Javadoc comments avoid unnecessary {@link} and {@linkplain} tags for APIs that are considered well-known. Linking well-known APIs can make comments harder to read without adding much value for the reader.

This check reports {@link} references to configured well-known APIs. Two properties are supported: wellKnownQualifiedPackages and wellKnownSimpleNames.

Both properties are needed because Checkstyle does not resolve Javadoc link targets. For example, java.lang.String contains the package name, so it can be matched through wellKnownQualifiedPackages. However, String only contains the simple name String, so it needs to be matched through wellKnownSimpleNames. Resolution of imports is not a solution since java.lang is implicitly imported.

For wellKnownQualifiedPackages, only references to classes that are direct members of a well-known package are reported. References to a member (for example, String#length()), a nested class (for example, System.Logger), a subpackage (for example, java.lang.ref.WeakReference), and a package itself (for example, java.lang.ref) are not reported.

Since:
14.1.0
  • Field Details

    • MSG_WELL_KNOWN_API

      public static final String MSG_WELL_KNOWN_API
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
    • MSG_WELL_KNOWN_PACKAGE

      public static final String MSG_WELL_KNOWN_PACKAGE
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
    • DOT

      private static final char DOT
      Dot.
      See Also:
    • wellKnownQualifiedPackages

      private Set<String> wellKnownQualifiedPackages
      Package names whose fully qualified API references should not be linked.
    • wellKnownSimpleNames

      private Set<String> wellKnownSimpleNames
      Simple API names that should not be linked.
  • Constructor Details

    • JavadocLinkWellKnownApiCheck

      public JavadocLinkWellKnownApiCheck()
      Creates a new JavadocLinkWellKnownApiCheck instance.
  • Method Details

    • 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:
    • setWellKnownQualifiedPackages

      public final void setWellKnownQualifiedPackages(String... values)
      Setter to specify package names whose fully qualified API references should not be linked.
      Parameters:
      values - user's values.
      Since:
      14.1.0
    • setWellKnownSimpleNames

      public final void setWellKnownSimpleNames(String... values)
      Setter to specify simple API names that should not be linked.
      Parameters:
      values - user's values.
      Since:
      14.1.0
    • 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
    • isWellKnownQualified

      private boolean isWellKnownQualified(String apiName)
      Checks whether the given API name belongs to a well-known qualified package.
      Parameters:
      apiName - the API name to check
      Returns:
      true if the API name belongs to a well-known qualified package