JavadocVariable

Since Checkstyle 3.0

On This Page

Description
Properties
Examples
Use Cases
- For fields which are in private or package access modifier
- For fields which are in public, protected, package or private access modifier
Example of Usage
Violation Messages
Fully Qualified Name
Parent Module

Description

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

Properties

name	description	type	default value	since
accessModifiers	Specify the set of access modifiers used to determine which fields should be checked. This includes both explicitly declared modifiers and implicit ones, such as package-private for fields without an explicit modifier. It also accounts for special cases where fields have implicit modifiers, such as `public static final` for interface fields and `public static` for enum constants, or where the nesting types accessibility is more restrictive and hides the nested field. Only fields matching the specified modifiers will be analyzed.	AccessModifierOption[]	`public, protected, package, private`	10.22.0
ignoreNamePattern	Specify the regexp to define variable names to ignore.	Pattern	`null`	5.8
tokens	tokens to check	subset of tokens ENUM_CONSTANT_DEF .	ENUM_CONSTANT_DEF .	3.0

Examples

To configure the default check:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocVariable"/>
  </module>
</module>

By default, this setting will report a violation if there is no javadoc for a field with any access modifier.


public class Example1 {
  private int a; // violation 'Missing a Javadoc comment for 'a'.'

  /**
   * Some description here
   */
  private int b;
  protected int c; // violation 'Missing a Javadoc comment for 'c'.'
  public int d; // violation 'Missing a Javadoc comment for 'd'.'
  /*package*/ int e; // violation 'Missing a Javadoc comment for 'e'.'

  public enum PublicEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }

  private enum PrivateEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }
}

To configure the check public access modifier:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocVariable">
      <property name="accessModifiers" value="public"/>
    </module>
  </module>
</module>

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


public class Example2 {
  private int a;

  /**
   * Some description here
   */
  private int b;
  protected int c;
  public int d; // violation 'Missing a Javadoc comment for 'd'.'
  /*package*/ int e;

  public enum PublicEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }

  private enum PrivateEnum {
    CONSTANT
  }
}

To configure the check for VARIABLE_DEF tokens only:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocVariable">
      <property name="tokens" value="VARIABLE_DEF"/>
    </module>
  </module>
</module>

Example3:


public class Example3 {
  private int a;     // violation 'Missing a Javadoc comment for 'a'.'

  /**
   * Some description here
   */
  private int b;
  protected int c;   // violation 'Missing a Javadoc comment for 'c'.'
  public int d;      // violation 'Missing a Javadoc comment for 'd'.'
  /*package*/ int e; // violation 'Missing a Javadoc comment for 'e'.'

  public enum PublicEnum {
    CONSTANT
  }

  private enum PrivateEnum {
    CONSTANT
  }
}

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


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

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


public class Example4 {
  private int a; // violation 'Missing a Javadoc comment for 'a'.'

  /**
   * Some description here
   */
  private int b;
  protected int c; // violation 'Missing a Javadoc comment for 'c'.'
  public int d; // violation 'Missing a Javadoc comment for 'd'.'
  /*package*/ int e; // violation 'Missing a Javadoc comment for 'e'.'

  public enum PublicEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }

  private enum PrivateEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }
}

Use Cases

To configure the check for fields which are in private or package access modifier:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocVariable">
      <property name="accessModifiers" value="private,package"/>
    </module>
  </module>
</module>

This setting will report a violation if there is no javadoc for private or package field.


public class UseCase1 {
  private int a; // violation 'Missing a Javadoc comment for 'a'.'

  /**
   * Some description here
   */
  private int b;
  protected int c;
  public int d;
  /*package*/ int e; // violation 'Missing a Javadoc comment for 'e'.'

  public enum PublicEnum {
    CONSTANT
  }

  private enum PrivateEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }
}

To configure the check for fields which are in public, protected, package or private access modifier:


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocVariable">
      <property name="accessModifiers" value="public,protected,package,private"/>
    </module>
  </module>
</module>

This check will not report a violation for local and anonymous inner classes with any configuration.


public class UseCase2 {
  // violation below 'Missing a Javadoc comment for 'variablePublic'.'
  public int variablePublic;
  // violation below 'Missing a Javadoc comment for 'variableProtected'.'
  protected int variableProtected;
  // violation below 'Missing a Javadoc comment for 'variablePackage'.'
  int variablePackage;
  // violation below 'Missing a Javadoc comment for 'variablePrivate'.'
  private int variablePrivate;

  public enum PublicEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }

  private enum PrivateEnum {
    CONSTANT // violation 'Missing a Javadoc comment for 'CONSTANT'.'
  }

  public void testMethodInnerClass() {

    // This check ignores local classes.
    class InnerClass {
      public int innerClassVariablePublic;
      protected int innerClassVariableProtected;
      int innerClassVariablePackage;
      private int innerClassVariablePrivate;
    }

    // This check ignores anonymous inner classes.
    Runnable runnable = new Runnable() {
      public int innerClassVariablePublic;
      protected int innerClassVariableProtected;
      int innerClassVariablePackage;
      private int innerClassVariablePrivate;
      public void run()
        {
          System.identityHashCode("running");
        }
    };
  }
}

Example of Usage

Violation Messages

javadoc.missing.named

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocVariableCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

TreeWalker