JavadocMethodCheck (checkstyle 8.35-SNAPSHOT API)

java.lang.Object
- com.puppycrawl.tools.checkstyle.api.AutomaticBean
- - com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
  - - com.puppycrawl.tools.checkstyle.api.AbstractCheck
    - - com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheck

All Implemented Interfaces:

Configurable, Contextualizable
```
public class JavadocMethodCheck
extends AbstractCheck
```
Checks the Javadoc of a method or constructor. 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 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)
 
```
- Property allowedAnnotations - Specify the list of annotations that allow missed documentation. Type is java.lang.String[]. Default value is Override.
- Property validateThrows - Control whether to validate throws tags. Type is boolean. Default value is false.
- Property scope - Specify the visibility scope where Javadoc comments are checked. Type is com.puppycrawl.tools.checkstyle.api.Scope. Default value is private.
- Property excludeScope - Specify the visibility scope where Javadoc comments are not checked. Type is com.puppycrawl.tools.checkstyle.api.Scope. Default value is null.
- Property allowMissingParamTags - Control whether to ignore violations when a method has parameters but does not have matching param tags in the javadoc. Type is boolean. 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. Type is boolean. Default value is false.
- Property tokens - tokens to check Type is int[]. 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, ignoring any missing param tags is:
```
 <module name="JavadocMethod">
   <property name="scope" value="public"/>
   <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>
 
```
To configure the check to validate throws tags, you can use following config.
```
 <module name="JavadocMethod">
   <property name="validateThrows" value="true"/>
 </module>
 
```
```
 /**
  * Actual exception thrown is child class of class that is declared in throws.
  * It is limitation of checkstyle (as checkstyle does not know type hierarchy).
  * Javadoc is valid not declaring FileNotFoundException
  * BUT checkstyle can not distinguish relationship between exceptions.
  * @param file some file
  * @throws IOException if some problem
  */
 public void doSomething8(File file) throws IOException {
     if (file == null) {
         throw new FileNotFoundException(); // violation
     }
 }

 /**
  * Exact throw type referencing in javadoc even first is parent of second type.
  * It is a limitation of checkstyle (as checkstyle does not know type hierarchy).
  * This javadoc is valid for checkstyle and for javadoc tool.
  * @param file some file
  * @throws IOException if some problem
  * @throws FileNotFoundException if file is not found
  */
 public void doSomething9(File file) throws IOException {
     if (file == null) {
         throw new FileNotFoundException();
     }
 }

 /**
  * Ignore try block, but keep catch and finally blocks.
  *
  * @param s String to parse
  * @return A positive integer
  */
 public int parsePositiveInt(String s) {
     try {
         int value = Integer.parseInt(s);
         if (value <= 0) {
             throw new NumberFormatException(value + " is negative/zero"); // ok, try
         }
         return value;
     } catch (NumberFormatException ex) {
         throw new IllegalArgumentException("Invalid number", ex); // violation, catch
     } finally {
         throw new IllegalStateException("Should never reach here"); // violation, finally
     }
 }

 /**
  * Try block without catch is not ignored.
  *
  * @return a String from standard input, if there is one
  */
 public String readLine() {
     try (Scanner sc = new Scanner(System.in)) {
         if (!sc.hasNext()) {
             throw new IllegalStateException("Empty input"); // violation, not caught
         }
         return sc.next();
     }
 }

 /**
  * Lambda expressions are ignored as we do not know when the exception will be thrown.
  *
  * @param s a String to be printed at some point in the future
  * @return a Runnable to be executed when the string is to be printed
  */
 public Runnable printLater(String s) {
     return () -> {
         if (s == null) {
             throw new NullPointerException(); // ok
         }
         System.out.println(s);
     };
 }
 
```
Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:
- javadoc.classInfo
- javadoc.duplicateTag
- javadoc.expectedTag
- javadoc.invalidInheritDoc
- javadoc.return.expected
- javadoc.unusedTag
- javadoc.unusedTagGeneral
Since:

3.0

Nested Class Summary
- Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
  AutomaticBean.OutputStreamOptions

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`MSG_CLASS_INFO` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_DUPLICATE_TAG` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_EXPECTED_TAG` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_INVALID_INHERIT_DOC` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_RETURN_EXPECTED` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_UNUSED_TAG` A key is pointing to the warning message text in "messages.properties" file.
`static String`	`MSG_UNUSED_TAG_GENERAL` A key is pointing to the warning message text in "messages.properties" file.

Constructor Summary

Constructors
Constructor and Description

JavadocMethodCheck()

Constructors
Constructor and Description
`JavadocMethodCheck()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`beginTree(DetailAST rootAST)` Called before the starting to process a tree.
`static List<DetailAST>`	`findTokensInAstByType(DetailAST root, int astType)` Finds node of specified type among root children, siblings, siblings children on any deep level.
`int[]`	`getAcceptableTokens()` The configurable token set.
`int[]`	`getDefaultTokens()` Returns the default token a check is interested in.
`int[]`	`getRequiredTokens()` The tokens that this check must be registered for.
`void`	`leaveToken(DetailAST ast)` Called after all the child nodes have been process.
`void`	`setAllowedAnnotations(String... userAnnotations)` Setter to specify the list of annotations that allow missed documentation.
`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.
`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.
`void`	`setExcludeScope(Scope excludeScope)` Setter to specify the visibility scope where Javadoc comments are not checked.
`void`	`setScope(Scope scope)` Setter to specify the visibility scope where Javadoc comments are checked.
`void`	`setValidateThrows(boolean value)` Setter to control whether to validate `throws` tags.
`void`	`visitToken(DetailAST ast)` Called to process a token.

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
clearMessages, destroy, finishTree, getFileContents, getLine, getLines, getMessages, getTabWidth, getTokenNames, init, isCommentNodesRequired, log, log, log, setFileContents, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MSG_CLASS_INFO
```
public static final 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 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 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 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 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 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 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(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.
  - 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
  - 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
  - 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
  - visitToken
```
public final void visitToken(DetailAST ast)
```
    Description copied from class: AbstractCheck
    
    Called to process a token.
    
    Overrides:
    
    visitToken in class AbstractCheck
    
    Parameters:
    
    ast - the token to process
  - 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
  - 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.

Class JavadocMethodCheck

Nested Class Summary

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

Methods inherited from class java.lang.Object

Field Detail

MSG_CLASS_INFO

MSG_UNUSED_TAG_GENERAL

MSG_INVALID_INHERIT_DOC

MSG_UNUSED_TAG

MSG_EXPECTED_TAG

MSG_RETURN_EXPECTED

MSG_DUPLICATE_TAG

Constructor Detail

JavadocMethodCheck

Method Detail

setValidateThrows

setAllowedAnnotations

setScope

setExcludeScope

setAllowMissingParamTags

setAllowMissingReturnTag

getRequiredTokens

getDefaultTokens

getAcceptableTokens

beginTree

visitToken

leaveToken

findTokensInAstByType