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

Class JavadocVariableCheck

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

    Checks that a variable has a Javadoc comment. Ignores serialVersionUID fields.

    • 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 ignoreNamePattern - Specify the regexp to define variable names to ignore. Type is java.util.regex.Pattern. Default value is null.
    • Property tokens - tokens to check Type is java.lang.String[]. Validation type is tokenSet. Default value is: ENUM_CONSTANT_DEF.

    To configure the default check: 

     <module name="JavadocVariable"/>

    By default, this setting will report a violation if there is no javadoc for any scope member. 

     public class Test {
   private int a; // violation, missing javadoc for private member

   /**
    * Some description here
    */
   private int b; // OK
   protected int c; // violation, missing javadoc for protected member
   public int d; // violation, missing javadoc for public member
   /*package*/ int e; // violation, missing javadoc for package member
 }

    To configure the check for public scope: 

     <module name="JavadocVariable">
   <property name="scope" value="public"/>
 </module>

    This setting will report a violation if there is no javadoc for public member.

     public class Test {
   private int a; // OK

   /**
    * Some description here
    */
   private int b; // OK
   protected int c; // OK
   public int d; // violation, missing javadoc for public member
   /*package*/ int e; // OK
 }

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

     <module name="JavadocVariable">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
 </module>

    This setting will report a violation if there is no javadoc for private member and ignores protected member. 

     public class Test {
   private int a; // violation, missing javadoc for private member

   /**
    * Some description here
    */
   private int b; // OK
   protected int c; // OK
   public int d; // OK
   /*package*/ int e; // violation, missing javadoc for package member
 }

    To ignore absence of Javadoc comments for variables with names log or logger: 

     <module name="JavadocVariable">
   <property name="ignoreNamePattern" value="log|logger"/>
 </module>

    This setting will report a violation if there is no javadoc for any scope member and ignores members with name log or logger. 

     public class Test {
   private int a; // violation, missing javadoc for private member

   /**
    * Some description here
    */
   private int b; // OK
   protected int c; // violation, missing javadoc for protected member
   public int d; // violation, missing javadoc for public member
   /*package*/ int e; // violation, missing javadoc for package member
   private int log; // OK
   private int logger; // OK
 }

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • javadoc.missing
    Since:
    3.0

    • Field Detail

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

      • ignoreNamePattern

        private java.util.regex.Pattern ignoreNamePattern
        Specify the regexp to define variable names to ignore.

    • Method Detail

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

      • setIgnoreNamePattern

        public void setIgnoreNamePattern​(java.util.regex.Pattern pattern)
        Setter to specify the regexp to define variable names to ignore.
        Parameters:
        pattern - a pattern.

      • 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

      • isIgnored

        private boolean isIgnored​(DetailAST ast)
        Decides whether the variable name of an AST is in the ignore list.
        Parameters:
        ast - the AST to check
        Returns:
        true if the variable name of ast is in the ignore list.

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