WriteTag

Since Checkstyle 4.2

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. Property tagSeverity is used for severity of events when the tag exists.

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 when tag is found and printed. SeverityLevel info 4.2
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 Test {
  /** some doc */
  void foo() {}
}

To configure Check to demand some special tag (for example @since) to be present on classes javadoc. 

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

Example: 

/**
* Some class
*/
public class Test { // violation as required tag is missed
  /** some doc */
  void foo() {} // OK, as methods are not checked by default
}

To configure Check to demand some special tag (for example @since) to be present on method javadocs also in addition to default tokens. 

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

Example: 

/**
* Some class
*/
public class Test { // violation as required tag is missed
  /** some doc */
  void foo() {} // violation as required tag is missed
}

To configure Check to demand @since tag to be present with digital value on method javadocs also in addition to default tokens. Attention: usage of non "ignore" in tagSeverity will print violation with such severity on each presence of such tag. 

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

Example: 

/**
* Some class
* @since 1.2
*/
public class Test {
  /** some doc
  * @since violation
  */
  void foo() {}
}

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.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker