GitHub Twitter Stackoverflow GoogleGroups JProfiler

WriteTag

Since Checkstyle 4.2

On This Page

Description

Requires user defined Javadoc tag to be present in Javadoc comment with defined format. To define the format for a tag, set property tagFormat to a regular expression. The common severity property is used for missing tag and tag format violations. Property tagSeverity is used only for javadoc.writeTag violations when the configured tag exists and its contents match tagFormat, or when tagFormat is not configured. No violation reported in case there is no javadoc.

Properties

name description type default value since
tag Specify the name of tag. String null 4.2
tagFormat Specify the regexp to match tag content. Pattern null 4.2
tagSeverity Specify the severity level for javadoc.writeTag violations when the configured tag is found and its contents match tagFormat, or when tagFormat is not configured. SeverityLevel info 4.2
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. boolean false 13.9.0
tokens tokens to check subset of tokens INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , METHOD_DEF , CTOR_DEF , ENUM_CONSTANT_DEF , ANNOTATION_FIELD_DEF , RECORD_DEF , COMPACT_CTOR_DEF . INTERFACE_DEF , CLASS_DEF , ENUM_DEF , ANNOTATION_DEF , RECORD_DEF . 4.2

Examples

Example of default Check configuration that do nothing. 


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

Example: 


/**
 * Some class
 *
 */
public class Example1 {

  /**
   * some doc
   * @since
   */
  void testMethod1() {}

  /**
   * some doc
   * @since 1.6
   */
  void testMethod1WithNumSince() {}

  /**
   * some doc
   * @since 1.1-beta
   */
  void testMethod1WithAlphaSince() {}

  /** some doc */
  public void testMethod2() {}

}

To configure Check to demand @since tag to be present on type javadoc. 


<module name="Checker">
  <module name="TreeWalker">
    <module name="WriteTag">
      <property name="tag" value="@since"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 *
 */
public class Example2 {
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
  /**
   * some doc
   * @since
   */
  void testMethod1() {} // ok, as methods are not checked by default

  /**
   * some doc
   * @since 1.6
   */
  void testMethod1WithNumSince() {}

  /**
   * some doc
   * @since 1.1-beta
   */
  void testMethod1WithAlphaSince() {}

  /** some doc */
  public void testMethod2() {}

}

To configure Check to demand @since tag to be present on type and method javadocs. Attention: all presence of tags are also highlighted as violation. 


<module name="Checker">
  <module name="TreeWalker">
    <module name="WriteTag">
      <property name="tokens"
                value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF,
                ANNOTATION_DEF, RECORD_DEF, METHOD_DEF" />
      <property name="tag" value="@since"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 *
 */
public class Example3 {
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
  /**
   * some doc
   * @since
   */
  void testMethod1() {}
  // violation 3 lines above 'Javadoc tag @since='
  /**
   * some doc
   * @since 1.6
   */
  void testMethod1WithNumSince() {}
  // violation 3 lines above 'Javadoc tag @since=1.6'
  /**
   * some doc
   * @since 1.1-beta
   */
  void testMethod1WithAlphaSince() {}
  // violation 3 lines above 'Javadoc tag @since=1.1-beta'
  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
}

To configure Check to demand @since tag to be present with digital value on method javadocs also in addition to default tokens. Set tagSeverity to ignore to suppress javadoc.writeTag violations for matching @since tags. Missing @since tags and tag format violations are still reported with the common severity property. 


<module name="Checker">
  <module name="TreeWalker">
    <module name="WriteTag">
      <property name="tokens"
                value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF,
                ANNOTATION_DEF, RECORD_DEF, METHOD_DEF" />
      <property name="tag" value="@since"/>
      <property name="tagFormat" value="^[1-9\.]+$"/>
      <property name="tagSeverity" value="ignore"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 *
 */
public class Example4 {
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
  /**
   * some doc
   * @since
   */
  void testMethod1() {}
  // violation 3 lines above 'Javadoc tag @since must match pattern'
  /**
   * some doc
   * @since 1.6
   */
  void testMethod1WithNumSince() {}

  /**
   * some doc
   * @since 1.1-beta
   */
  void testMethod1WithAlphaSince() {}
  // violation 3 lines above 'Javadoc tag @since must match pattern'
  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
}

To configure Check to demand @since tag to be present with digital value on method javadocs also in addition to default tokens. The tagSeverity property is set to error, but tag format violations are still reported with the common severity property. 


<module name="Checker">
  <module name="TreeWalker">
    <module name="WriteTag">
      <property name="tokens"
                value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF,
                ANNOTATION_DEF, RECORD_DEF, METHOD_DEF" />
      <property name="tag" value="@since"/>
      <property name="tagFormat" value="^[1-9\.]+$"/>
      <property name="tagSeverity" value="error"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 *
 */
public class Example5 {
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
  /**
   * some doc
   * @since
   */
  void testMethod1() {}
  // violation 3 lines above 'Javadoc tag @since must match pattern'
  /**
   * some doc
   * @since 1.6
   */
  void testMethod1WithNumSince() {}
  // violation 3 lines above 'Javadoc tag @since=1.6'
  /**
   * some doc
   * @since 1.1-beta
   */
  void testMethod1WithAlphaSince() {}
  // violation 3 lines above 'Javadoc tag @since must match pattern'
  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Javadoc comment is missing @since tag.'
}

Use Cases

To configure Check to forbid @author tags in Javadoc comments. The SuppressionSingleFilter suppresses missing tag violations, as missing @author tags are desired in this use case. 


<module name="Checker">
  <module name=
      "com.puppycrawl.tools.checkstyle.filters.SuppressionSingleFilter">
    <property name="checks" value="WriteTag"/>
    <property name="message"
              value="^Javadoc comment is missing @author tag\.$"/>
  </module>

  <module name="TreeWalker">
    <module name="WriteTag">
      <property name="tokens"
                value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF,
                ANNOTATION_DEF, RECORD_DEF, METHOD_DEF, CTOR_DEF,
                ENUM_CONSTANT_DEF, ANNOTATION_FIELD_DEF,
                COMPACT_CTOR_DEF" />
      <property name="tag" value="@author"/>
      <property name="tagSeverity" value="error"/>
      <message key="javadoc.writeTag" value="No {0} tags should be used."/>
    </module>
  </module>
</module>

Example: 


// violation 4 lines below 'No @author tags should be used.'
/**
 * Some class.
 *
 * @author John Doe
 */
public class UseCase1 {

  /**
   * Helper without author tag.
   */
  void testMethod() {}
}

Example of Usage

Violation Messages

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

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

Parent Module

TreeWalker