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

Class JavadocTypeCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public class JavadocTypeCheck
extends AbstractCheck
    Checks the Javadoc of a type.

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

    • Field Detail

      • MSG_JAVADOC_MISSING

        public static final java.lang.String MSG_JAVADOC_MISSING
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

      • MSG_UNKNOWN_TAG

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

      • MSG_TAG_FORMAT

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

      • MSG_MISSING_TAG

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

      • MSG_UNUSED_TAG

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

      • MSG_UNUSED_TAG_GENERAL

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

      • OPEN_ANGLE_BRACKET

        private static final java.lang.String OPEN_ANGLE_BRACKET
        Open angle bracket literal.
        See Also:
        Constant Field Values

      • CLOSE_ANGLE_BRACKET

        private static final java.lang.String CLOSE_ANGLE_BRACKET
        Close angle bracket literal.
        See Also:
        Constant Field Values

      • TYPE_NAME_IN_JAVADOC_TAG

        private static final java.util.regex.Pattern TYPE_NAME_IN_JAVADOC_TAG
        Pattern to match type name within angle brackets in javadoc param tag.

      • TYPE_NAME_IN_JAVADOC_TAG_SPLITTER

        private static final java.util.regex.Pattern TYPE_NAME_IN_JAVADOC_TAG_SPLITTER
        Pattern to split type name field in javadoc param tag.

      • scope

        private Scope scope
        The scope to check for.

      • excludeScope

        private Scope excludeScope
        The visibility scope where Javadoc comments shouldn't be checked.

      • authorFormat

        private java.util.regex.Pattern authorFormat
        Compiled regexp to match author tag content.

      • versionFormat

        private java.util.regex.Pattern versionFormat
        Compiled regexp to match version tag content.

      • allowMissingParamTags

        private boolean allowMissingParamTags
        Controls whether to ignore errors when a method has type parameters but does not have matching param tags in the javadoc. Defaults to false.

      • allowUnknownTags

        private boolean allowUnknownTags
        Controls whether to flag errors for unknown tags. Defaults to false.

    • Constructor Detail

      • JavadocTypeCheck

        public JavadocTypeCheck()

    • Method Detail

      • setScope

        public void setScope​(Scope scope)
        Sets the scope to check.
        Parameters:
        scope - a scope.

      • setExcludeScope

        public void setExcludeScope​(Scope excludeScope)
        Set the excludeScope.
        Parameters:
        excludeScope - a scope.

      • setAuthorFormat

        public void setAuthorFormat​(java.util.regex.Pattern pattern)
        Set the author tag pattern.
        Parameters:
        pattern - a pattern.

      • setVersionFormat

        public void setVersionFormat​(java.util.regex.Pattern pattern)
        Set the version format pattern.
        Parameters:
        pattern - a pattern.

      • setAllowMissingParamTags

        public void setAllowMissingParamTags​(boolean flag)
        Controls whether to allow a type which has type parameters to omit matching param tags in the javadoc. Defaults to false.
        Parameters:
        flag - a Boolean value

      • setAllowUnknownTags

        public void setAllowUnknownTags​(boolean flag)
        Controls whether to flag errors for unknown tags. Defaults to false.
        Parameters:
        flag - a Boolean value

      • 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.
        Specified by:
        getDefaultTokens in class AbstractCheck
        Returns:
        the default tokens
        See Also:
        TokenTypes

      • 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.
        Specified by:
        getAcceptableTokens in class AbstractCheck
        Returns:
        the token set this check is designed for.
        See Also:
        TokenTypes

      • getRequiredTokens

        public int[] getRequiredTokens()
        Description copied from class: AbstractCheck
        The tokens that this check must be registered for.
        Specified by:
        getRequiredTokens in class AbstractCheck
        Returns:
        the token set this must be registered for.
        See Also:
        TokenTypes

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

      • getJavadocTags

        private java.util.List<JavadocTag> getJavadocTags​(TextBlock textBlock)
        Gets all standalone tags from a given javadoc.
        Parameters:
        textBlock - the Javadoc comment to process.
        Returns:
        all standalone tags from the given javadoc.

      • checkTag

        private void checkTag​(int lineNo,
                      java.util.List<JavadocTag> tags,
                      java.lang.String tagName,
                      java.util.regex.Pattern formatPattern)
        Verifies that a type definition has a required tag.
        Parameters:
        lineNo - the line number for the type definition.
        tags - tags from the Javadoc comment for the type definition.
        tagName - the required tag name.
        formatPattern - regexp for the tag value.

      • checkTypeParamTag

        private void checkTypeParamTag​(int lineNo,
                               java.util.List<JavadocTag> tags,
                               java.lang.String typeParamName)
        Verifies that a type definition has the specified param tag for the specified type parameter name.
        Parameters:
        lineNo - the line number for the type definition.
        tags - tags from the Javadoc comment for the type definition.
        typeParamName - the name of the type parameter

      • checkUnusedTypeParamTags

        private void checkUnusedTypeParamTags​(java.util.List<JavadocTag> tags,
                                      java.util.List<java.lang.String> typeParamNames)
        Checks for unused param tags for type parameters.
        Parameters:
        tags - tags from the Javadoc comment for the type definition.
        typeParamNames - names of type parameters

      • extractTypeParamNameFromTag

        private static java.lang.String extractTypeParamNameFromTag​(JavadocTag tag)
        Extracts type parameter name from tag.
        Parameters:
        tag - javadoc tag to extract parameter name
        Returns:
        extracts type parameter name from tag