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. 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 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 Example1 {

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

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

}

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 Example2 {
  // violation 1 lines above 'Type Javadoc comment is missing @since tag.'
  /**
   * some doc
   * @since
   */
  void testMethod1() {} // ok, as methods are not checked by default

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

}

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="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 'Type Javadoc comment is missing @since tag.'
  // violation 3 lines below 'Javadoc tag @since='
  /**
   * some doc
   * @since
   */
  void testMethod1() {}

  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Type 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. Attention: it is required to set "ignore" in tagSeverity.


<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
 * @since 1.2
 */
public class Example4 {
  // violation 3 lines below 'Type Javadoc tag @since'
  /**
   * some doc
   * @since
   */
  void testMethod1() {}

  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Type Javadoc comment is missing @since tag.'
}

To configure Check to demand @since tag and in the same time print violation with specific severity on each presence of such tag.


<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:


// violation 3 lines below 'Javadoc tag @since=1.2'
/**
 * Some class
 * @since 1.2
 */
public class Example5 {
  // violation 3 lines below 'Type Javadoc tag @since'
  /**
   * some doc
   * @since
   */
  void testMethod1() {}

  /** some doc */
  public void testMethod2() {}
  // violation 1 lines above 'Type Javadoc comment is missing @since tag.'
}

Example of Usage

Checkstyle Style

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