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

Class JavadocMethodCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public class JavadocMethodCheck
extends AbstractCheck

    Checks the Javadoc of a method or constructor. By default, check does not validate methods and constructors for unused throws. To allow documented exceptions derived from java.lang.RuntimeException that are not declared, set property allowUndeclaredRTE to true. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to a different scope.

    Violates parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags. Violates exceptions which are declared to be thrown, but for which no throws tag is present can be suppressed by defining property allowMissingThrowsTags. Violates methods which return non-void but for which no return tag is present can be suppressed by defining property allowMissingReturnTag.

    Javadoc is not required on a method that is tagged with the @Override annotation. However under Java 5 it is not possible to mark a method required for an interface (this was corrected under Java 6). Hence Checkstyle supports using the convention of using a single {@inheritDoc} tag instead of all the other tags.

    Note that only inheritable items will allow the {@inheritDoc} tag to be used in place of comments. Static methods at all visibilities, private non-static methods and constructors are not inheritable.

    For example, if the following method is implementing a method required by an interface, then the Javadoc could be done as: 

     /** {@inheritDoc} */
 public int checkReturnTag(final int aTagIndex,
                           JavadocTag[] aTags,
                           int aLineNo)

    The classpath may need to be configured to locate the class information. The classpath configuration is dependent on the mechanism used to invoke Checkstyle.

    • Property allowedAnnotations - Specify the list of annotations that allow missed documentation. Default value is Override.
    • Property validateThrows - Control whether to validate throws tags. Default value is false.
    • Property scope - Specify the visibility scope where Javadoc comments are checked. Default value is private.
    • Property excludeScope - Specify the visibility scope where Javadoc comments are not checked. Default value is null.
    • Property allowUndeclaredRTE - Control whether to allow documented exceptions that are not declared if they are a subclass of java.lang.RuntimeException. Default value is false.
    • Property allowThrowsTagsForSubclasses - Control whether to allow documented exceptions that are subclass of one of declared exception. Default value is false.
    • Property allowMissingParamTags - Control whether to ignore violations when a method has parameters but does not have matching param tags in the javadoc. Default value is false.
    • Property allowMissingThrowsTags - Control whether to ignore violations when a method declares that it throws exceptions but does not have matching throws tags in the javadoc. Default value is false.
    • Property allowMissingReturnTag - Control whether to ignore violations when a method returns non-void type and does not have a return tag in the javadoc. Default value is false.
    • Property logLoadErrors - Control checkstyle's error handling when a class loading fails. This check may need to load exception classes mentioned in the @throws tag to check whether they are RuntimeExceptions. If set to false a classpath configuration problem is assumed and the TreeWalker stops operating on the class completely. If set to true (the default), checkstyle assumes a typo or refactoring problem in the javadoc and logs the problem in the normal checkstyle report (potentially masking a configuration error). Default value is true.
    • Property suppressLoadErrors - Control whether to suppress violations when a class loading fails. When logLoadErrors is set to true, the TreeWalker completely processes a class and displays any problems with loading exceptions as checkstyle violations. When this property is set to true, the violations generated when logLoadErrors is set true are suppressed from being reported as violations in the checkstyle report. Default value is false.
    • Property tokens - tokens to check Default value is: METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF.

    To configure the default check: 

     <module name="JavadocMethod"/>

    To configure the check for public scope and to allow documentation of undeclared RuntimeExceptions: 

     <module name="JavadocMethod">
   <property name="scope" value="public"/>
   <property name="allowUndeclaredRTE" value="true"/>
 </module>

    To configure the check for for public scope, to allow documentation of undeclared RuntimeExceptions, while ignoring any missing param tags is: 

     <module name="JavadocMethod">
   <property name="scope" value="public"/>
   <property name="allowUndeclaredRTE" value="true"/>
   <property name="allowMissingParamTags" value="true"/>
 </module>

    To configure the check for methods which are in private, but not in protected scope: 

     <module name="JavadocMethod">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
 </module>
    Since:
    3.0

    • Field Detail

      • MSG_CLASS_INFO

        public static final java.lang.String MSG_CLASS_INFO
        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

      • MSG_INVALID_INHERIT_DOC

        public static final java.lang.String MSG_INVALID_INHERIT_DOC
        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_EXPECTED_TAG

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

      • MSG_RETURN_EXPECTED

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

      • MSG_DUPLICATE_TAG

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

    • Constructor Detail

      • JavadocMethodCheck

        public JavadocMethodCheck()

    • Method Detail

      • setValidateThrows

        public void setValidateThrows​(boolean value)
        Setter to control whether to validate throws tags.
        Parameters:
        value - user's value.

      • setAllowedAnnotations

        public void setAllowedAnnotations​(java.lang.String... userAnnotations)
        Setter to specify the list of annotations that allow missed documentation.
        Parameters:
        userAnnotations - user's value.

      • setScope

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

      • setExcludeScope

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

      • setAllowUndeclaredRTE

        public void setAllowUndeclaredRTE​(boolean flag)
        Setter to control whether to allow documented exceptions that are not declared if they are a subclass of java.lang.RuntimeException.
        Parameters:
        flag - a Boolean value

      • setAllowThrowsTagsForSubclasses

        public void setAllowThrowsTagsForSubclasses​(boolean flag)
        Setter to control whether to allow documented exceptions that are subclass of one of declared exception.
        Parameters:
        flag - a Boolean value

      • setAllowMissingParamTags

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

      • setAllowMissingThrowsTags

        public void setAllowMissingThrowsTags​(boolean flag)
        Setter to control whether to ignore violations when a method declares that it throws exceptions but does not have matching throws tags in the javadoc.
        Parameters:
        flag - a Boolean value

      • setAllowMissingReturnTag

        public void setAllowMissingReturnTag​(boolean flag)
        Setter to control whether to ignore violations when a method returns non-void type and does not have a return tag in the javadoc.
        Parameters:
        flag - a Boolean value

      • setLogLoadErrors

        @Deprecated
public final void setLogLoadErrors​(boolean logLoadErrors)
        Deprecated.
        No substitute.
        Setter to control checkstyle's error handling when a class loading fails. This check may need to load exception classes mentioned in the @throws tag to check whether they are RuntimeExceptions. If set to false a classpath configuration problem is assumed and the TreeWalker stops operating on the class completely. If set to true(the default), checkstyle assumes a typo or refactoring problem in the javadoc and logs the problem in the normal checkstyle report (potentially masking a configuration error).
        Parameters:
        logLoadErrors - true if errors should be logged

      • setSuppressLoadErrors

        @Deprecated
public final void setSuppressLoadErrors​(boolean suppressLoadErrors)
        Deprecated.
        No substitute.
        Setter to control whether to suppress violations when a class loading fails. When logLoadErrors is set to true, the TreeWalker completely processes a class and displays any problems with loading exceptions as checkstyle violations. When this property is set to true, the violations generated when logLoadErrors is set true are suppressed from being reported as violations in the checkstyle report.
        Parameters:
        suppressLoadErrors - true if errors shouldn't be shown

      • getRequiredTokens

        public final 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

      • 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

      • 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 AbstractCheck
        Parameters:
        rootAST - the root of the tree

      • leaveToken

        public final void leaveToken​(DetailAST ast)
        Description copied from class: AbstractCheck
        Called after all the child nodes have been process.
        Overrides:
        leaveToken in class AbstractCheck
        Parameters:
        ast - the token leaving