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. Violations are reported only when the configured tag is missing or when the tag content does not match tagFormat. No violation is reported when the tag is present and matches tagFormat (or when tagFormat is not configured). No violation reported in case there is no javadoc. To forbid tags instead of requiring them, use IllegalBlockTag.

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
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. Matching tags produce no 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() {}

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

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

  /** 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. Missing @since tags and tag format violations are 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\.]+$"/>
    </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.'
}

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