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

Class JavadocMethodCheck

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.JavadocMethodCheck
All Implemented Interfaces:
Configurable, Contextualizable
public class JavadocMethodCheck extends AbstractJavadocCheck
Checks the Javadoc of a method or constructor.

Violates parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags.

Violates methods which return non-void but for which no return tag is present can be suppressed by defining property allowMissingReturnTag.

Violates exceptions which are declared to be thrown (by throws in the method signature or by throw new in the method body), but for which no throws tag is present by activation of property validateThrows. Note that throw new is not checked in the following places:

  • Inside a try block (with catch). It is not possible to determine if the thrown exception can be caught by the catch block as there is no knowledge of the inheritance hierarchy, so the try block is ignored entirely. However, catch and finally blocks, as well as try blocks without catch, are still checked.
  • Local classes, anonymous classes and lambda expressions. It is not known when the throw statements inside such classes are going to be evaluated, so they are ignored.

ATTENTION: Checkstyle does not have information about hierarchy of exception types so usage of base class is considered as separate exception type. As workaround, you need to specify both types in javadoc (parent and exact type).

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)
Since:
3.0

  • Field Details

  • Constructor Details

  • Method Details

    • setAllowInlineReturn

      public void setAllowInlineReturn(boolean value)
      Setter to control whether to allow inline return tags.
      Parameters:
      value - a boolean value
      Since:
      10.23.0

    • setValidateThrows

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

    • setAllowedAnnotations

      public void setAllowedAnnotations(String... userAnnotations)
      Setter to specify annotations that allow missed documentation.
      Parameters:
      userAnnotations - user's value.
      Since:
      6.0

    • setAccessModifiers

      public void setAccessModifiers(AccessModifierOption... accessModifiers)
      Setter to specify the access modifiers where Javadoc comments are checked.
      Parameters:
      accessModifiers - access modifiers.
      Since:
      8.42

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

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

    • 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

    • getRequiredTokens

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

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

    • visitToken

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

    • 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

    • collectReturn

      private void collectReturn(DetailNode ast)
      Collects a return tag if it has a description.
      Parameters:
      ast - the return tag node

    • collectInheritDoc

      private void collectInheritDoc()
      Collects an inheritDoc tag.

    • collectParam

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

    • collectThrows

      private void collectThrows(DetailNode ast, String tagName)
      Collects a throws or exception tag.
      Parameters:
      ast - the throws or exception tag node
      tagName - the tag name

    • checkCollectedTags

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

    • shouldCheck

      private boolean shouldCheck(DetailAST ast)
      Checks whether the given declaration should be validated.

      The declaration is checked only when both its own access modifier and the access modifier of the surrounding type match the configured accessModifiers.

      Parameters:
      ast - the method, constructor, annotation field, or compact constructor AST node to check
      Returns:
      true if the declaration is inside the configured access scope

    • getRecordComponents

      private static List<DetailAST> getRecordComponents(DetailAST recordDef)
      Retrieves the list of record components from a given record definition.
      Parameters:
      recordDef - the AST node representing the record definition
      Returns:
      a list of AST nodes representing the record components

    • getRecordDef

      private static DetailAST getRecordDef(DetailAST ast)
      Finds the nearest ancestor record definition node for the given AST node.
      Parameters:
      ast - the AST node to start searching from
      Returns:
      the nearest RECORD_DEF AST node, or null if not found

    • hasShortCircuitTag

      private boolean hasShortCircuitTag(DetailAST ast, List<JavadocTag> tags)
      Validates whether the Javadoc has a short circuit tag. Currently, this is the inheritTag. Any violations are logged.
      Parameters:
      ast - the construct being checked
      tags - the list of Javadoc tags associated with the construct
      Returns:
      true if the construct has a short circuit tag.

    • getParameters

      private static List<DetailAST> getParameters(DetailAST ast)
      Computes the parameter nodes for a method.
      Parameters:
      ast - the method node.
      Returns:
      the list of parameter nodes for ast.

    • getThrows

      private static List<JavadocMethodCheck.ExceptionInfo> getThrows(DetailAST ast)
      Computes the exception nodes for a method.
      Parameters:
      ast - the method node.
      Returns:
      the list of exception nodes for ast.

    • getThrowed

      private static List<JavadocMethodCheck.ExceptionInfo> getThrowed(DetailAST methodAst)
      Get ExceptionInfo for all exceptions that throws in method code by 'throw new'.
      Parameters:
      methodAst - method DetailAST object where to find exceptions
      Returns:
      list of ExceptionInfo

    • getExceptionInfo

      private static JavadocMethodCheck.ExceptionInfo getExceptionInfo(DetailAST ast)
      Get ExceptionInfo instance.
      Parameters:
      ast - DetailAST object where to find exceptions node;
      Returns:
      ExceptionInfo

    • getFirstClassNameNode

      private static DetailAST getFirstClassNameNode(DetailAST ast)
      Get node where class name of exception starts.
      Parameters:
      ast - DetailAST object where to find exceptions node;
      Returns:
      exception node where class name starts

    • isInIgnoreBlock

      private static boolean isInIgnoreBlock(DetailAST methodBodyAst, DetailAST throwAst)
      Checks if a 'throw' usage is contained within a block that should be ignored. Such blocks consist of try (with catch) blocks, local classes, anonymous classes, and lambda expressions. Note that a try block without catch is not considered.
      Parameters:
      methodBodyAst - DetailAST node representing the method body
      throwAst - DetailAST node representing the 'throw' literal
      Returns:
      true if throwAst is inside a block that should be ignored

    • combineExceptionInfo

      private static List<JavadocMethodCheck.ExceptionInfo> combineExceptionInfo(Collection<JavadocMethodCheck.ExceptionInfo> first, Iterable<JavadocMethodCheck.ExceptionInfo> second)
      Combine ExceptionInfo collections together by matching names.
      Parameters:
      first - the first collection of ExceptionInfo
      second - the second collection of ExceptionInfo
      Returns:
      combined list of ExceptionInfo

    • findTokensInAstByType

      public static List<DetailAST> findTokensInAstByType(DetailAST root, int astType)
      Finds node of specified type among root children, siblings, siblings children on any deep level.
      Parameters:
      root - DetailAST
      astType - value of TokenType
      Returns:
      List of DetailAST nodes which matches the predicate.

    • checkRecordParamTags

      private void checkRecordParamTags(List<JavadocTag> tags, DetailAST compactDef, boolean reportExpectedTags)
      Checks if all record components in a compact constructor have corresponding @param tags. Reports missing or extra @param tags in the Javadoc.
      Parameters:
      tags - the list of Javadoc tags
      compactDef - the compact constructor AST node
      reportExpectedTags - whether to report missing @param tags

    • checkParamTags

      private void checkParamTags(List<JavadocTag> tags, DetailAST parent, boolean reportExpectedTags)
      Checks a set of tags for matching parameters.
      Parameters:
      tags - the tags to check
      parent - the node which takes the parameters
      reportExpectedTags - whether we should report if do not find expected tag

    • searchMatchingTypeParameter

      private static boolean searchMatchingTypeParameter(Iterable<DetailAST> typeParams, String requiredTypeName)
      Returns true if required type found in type parameters.
      Parameters:
      typeParams - collection of type parameters
      requiredTypeName - name of required type
      Returns:
      true if required type found in type parameters.

    • removeMatchingParam

      private static boolean removeMatchingParam(Iterable<DetailAST> params, String paramName)
      Remove parameter from params collection by name.
      Parameters:
      params - collection of DetailAST parameters
      paramName - name of parameter
      Returns:
      true if parameter found and removed

    • checkReturnTag

      private void checkReturnTag(List<JavadocTag> tags, int lineNo, boolean reportExpectedTags)
      Checks for only one return tag. All return tags will be removed from the supplied list.
      Parameters:
      tags - the tags to check
      lineNo - the line number of the expected tag
      reportExpectedTags - whether we should report if do not find expected tag

    • checkThrowsTags

      private void checkThrowsTags(List<JavadocTag> tags, List<JavadocMethodCheck.ExceptionInfo> throwsList, boolean reportExpectedTags)
      Checks a set of tags for matching throws.
      Parameters:
      tags - the tags to check
      throwsList - the throws to check
      reportExpectedTags - whether we should report if do not find expected tag

    • processThrows

      private static void processThrows(Iterable<JavadocMethodCheck.ExceptionInfo> throwsIterable, String documentedClassName)
      Verifies that documented exception is in throws.
      Parameters:
      throwsIterable - collection of throws
      documentedClassName - documented exception class name

    • isExceptionInfoSame

      private static boolean isExceptionInfoSame(JavadocMethodCheck.ExceptionInfo info1, JavadocMethodCheck.ExceptionInfo info2)
      Check that ExceptionInfo objects are same by name.
      Parameters:
      info1 - ExceptionInfo object
      info2 - ExceptionInfo object
      Returns:
      true is ExceptionInfo object have the same name

    • isClassNamesSame

      private static boolean isClassNamesSame(String class1, String class2)
      Check that class names are same by short name of class. If some class name is fully qualified it is cut to short name.
      Parameters:
      class1 - class name
      class2 - class name
      Returns:
      true is ExceptionInfo object have the same name