Class JavadocTypeCheck

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.JavadocTypeCheck
All Implemented Interfaces:
Configurable, Contextualizable
public class JavadocTypeCheck extends AbstractJavadocCheck
Checks the Javadoc comments for type definitions. By default, does not check for author or version tags. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to one of the Scope constants. To define the format for an author tag or a version tag, set property authorFormat or versionFormat respectively to a pattern.

Does not perform checks for author and version tags for inner classes, as they should be redundant because of outer class.

Does not perform checks for type definitions that do not have any Javadoc comments.

Error messages about type parameters and record components for which no param tags are present can be suppressed by defining property allowMissingParamTags.

Since:
3.0

  • Field Details

    • MSG_UNKNOWN_TAG

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

    • MSG_TAG_FORMAT

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

    • MSG_MISSING_TAG

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

    • MSG_MISSING_TAG_WITH_QUOTES

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

    • MSG_UNUSED_TAG

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

    • MSG_UNUSED_TAG_GENERAL

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

    • OPEN_ANGLE_BRACKET

      private static final String OPEN_ANGLE_BRACKET
      Open angle bracket literal.
      See Also:

    • CLOSE_ANGLE_BRACKET

      private static final String CLOSE_ANGLE_BRACKET
      Close angle bracket literal.
      See Also:

    • AUTHOR_TAG_NAME

      private static final String AUTHOR_TAG_NAME
      Author tag literal.
      See Also:

    • VERSION_TAG_NAME

      private static final String VERSION_TAG_NAME
      Version tag literal.
      See Also:

    • javadocTags

      private final Map<DetailNode, String> javadocTags
      Javadoc param tag names, mapped by their corresponding Javadoc node.

    • scope

      private Scope scope
      Specify the visibility scope where Javadoc comments are checked.

    • excludeScope

      private Scope excludeScope
      Specify the visibility scope where Javadoc comments are not checked.

    • authorFormat

      private Pattern authorFormat
      Specify the pattern for @author tag.

    • versionFormat

      private Pattern versionFormat
      Specify the pattern for @version tag.

    • allowMissingParamTags

      private boolean allowMissingParamTags
      Control whether to ignore violations when a class has type parameters but does not have matching param tags in the Javadoc.

    • allowUnknownTags

      private boolean allowUnknownTags
      Control whether to ignore violations when a Javadoc tag is not recognised.

    • allowedAnnotations

      private Set<String> allowedAnnotations
      Specify annotations that allow skipping validation at all. Only short names are allowed, e.g. Generated.

    • currentAst

      private DetailAST currentAst
      Java AST node whose attached Javadoc is currently being processed.

    • authorTagIsPresent

      private boolean authorTagIsPresent
      Whether an @author tag was found in the current Javadoc tree.

    • versionTagIsPresent

      private boolean versionTagIsPresent
      Whether a @version tag was found in the current Javadoc tree.

  • Constructor Details

    • JavadocTypeCheck

      public JavadocTypeCheck()
      Creates a new JavadocTypeCheck instance.

  • Method Details

    • setScope

      public void setScope(Scope scope)
      Setter to specify the visibility scope where Javadoc comments are checked.
      Parameters:
      scope - a scope.
      Since:
      3.0

    • setExcludeScope

      public void setExcludeScope(Scope excludeScope)
      Setter to specify the visibility scope where Javadoc comments are not checked.
      Parameters:
      excludeScope - a scope.
      Since:
      3.4

    • setAuthorFormat

      public void setAuthorFormat(Pattern pattern)
      Setter to specify the pattern for @author tag.
      Parameters:
      pattern - a pattern.
      Since:
      3.0

    • setVersionFormat

      public void setVersionFormat(Pattern pattern)
      Setter to specify the pattern for @version tag.
      Parameters:
      pattern - a pattern.
      Since:
      3.0

    • setAllowMissingParamTags

      public void setAllowMissingParamTags(boolean flag)
      Setter to control whether to ignore violations when a class has type parameters but does not have matching param tags in the Javadoc.
      Parameters:
      flag - a Boolean value
      Since:
      4.0

    • setAllowUnknownTags

      public void setAllowUnknownTags(boolean flag)
      Setter to control whether to ignore violations when a Javadoc tag is not recognised.
      Parameters:
      flag - a Boolean value
      Since:
      5.1

    • setAllowedAnnotations

      public void setAllowedAnnotations(String... userAnnotations)
      Setter to specify annotations that allow skipping validation at all. Only short names are allowed, e.g. Generated.
      Parameters:
      userAnnotations - user's value.
      Since:
      8.15

    • setViolateExecutionOnNonTightHtml

      public void setViolateExecutionOnNonTightHtml(boolean shouldReportViolation)
      Setter to control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules.
      Overrides:
      setViolateExecutionOnNonTightHtml in class AbstractJavadocCheck
      Parameters:
      shouldReportViolation - value to which the field shall be set to
      Since:
      8.3

    • 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

    • finishJavadocTree

      public void finishJavadocTree(DetailNode rootAst)
      Description copied from class: AbstractJavadocCheck
      Called after finished processing a tree.
      Overrides:
      finishJavadocTree in class AbstractJavadocCheck
      Parameters:
      rootAst - the root of the tree

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

    • 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

    • getDefaultTokens

      public int[] getDefaultTokens()
      Description copied from class: AbstractCheck
      Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.
      Overrides:
      getDefaultTokens in class AbstractJavadocCheck
      Returns:
      the default tokens
      See Also:

    • getAcceptableTokens

      public int[] getAcceptableTokens()
      Description copied from class: AbstractCheck
      The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.
      Overrides:
      getAcceptableTokens in class AbstractJavadocCheck
      Returns:
      the token set this check is designed for.
      See Also:

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

    • 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

    • shouldCheck

      private boolean shouldCheck(DetailAST ast)
      Whether we should check this node.
      Parameters:
      ast - a given node.
      Returns:
      whether we should check a given node.

    • collectParam

      private void collectParam(DetailNode ast)
      Collects a param tag.
      Parameters:
      ast - the param tag node

    • checkUnknownTag

      private void checkUnknownTag(DetailNode ast)
      Checks an unknown Javadoc tag.
      Parameters:
      ast - the unknown tag node

    • checkTagFormat

      private void checkTagFormat(DetailNode ast, String tagName, Pattern format)
      Checks a Javadoc tag description against the expected format.
      Parameters:
      ast - the Javadoc tag node
      tagName - the tag name
      format - expected format for the tag description

    • checkCollectedParamTags

      private void checkCollectedParamTags()
      Checks collected Javadoc param tags against the current AST node.

    • getRecordComponentNames

      private static List<String> getRecordComponentNames(DetailAST node)
      Collects the record component names in a record definition.
      Parameters:
      node - the possible record definition AST
      Returns:
      the record component names in this record definition