GitHub Twitter Stackoverflow GoogleGroups JProfiler

IllegalBlockTag

Since Checkstyle 13.10.0

On This Page

Description

Detects a user-defined Javadoc block tag and reports a violation when the tag is present with text that does not match tagTextPattern. With the default pattern ^$ (same as Regexp format default; matches only empty content), any non-empty text of the configured tag is a violation. No violation is reported when there is no Javadoc or when tag is not configured.

Properties

name description type default value since
tag Specify the name of tag. String null 13.10.0
tagTextPattern Specify the regexp that tag content is allowed to match. Content that does not match is treated as illegal. Pattern ^$ 13.10.0
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.10.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 , METHOD_DEF , CTOR_DEF , ENUM_CONSTANT_DEF , ANNOTATION_FIELD_DEF , RECORD_DEF , COMPACT_CTOR_DEF . 13.10.0

Examples

Example of default Check configuration that does nothing. 


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

Example: 


/**
 * Some class
 * @since 1.1-beta
 */
public class Example1 {

  /**
   * some doc
   * @todo remove
   * @since 1.1-beta
   */
  void testMethod1() {}

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

  /**
   * some doc
   * @todo later
   * @since 1.2
   */
  void testMethod3() {}

}

To configure Check to forbid the @todo block tag wherever it appears. The default tagTextPattern is ^$, so any non-empty tag text is a violation. 


<module name="Checker">
  <module name="TreeWalker">
    <module name="IllegalBlockTag">
      <property name="tag" value="@todo"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 * @since 1.1-beta
 */
public class Example2 {

  /**
   * some doc
   * @todo remove
   * @since 1.1-beta
   */
  void testMethod1() {}
  // violation 4 lines above 'Block tag 'todo' is matched illegal pattern'
  /**
   * some doc
   * @since 1.6
   */
  void testMethod2() {}

  /**
   * some doc
   * @todo later
   * @since 1.2
   */
  void testMethod3() {}
  // violation 4 lines above 'Block tag 'todo' is matched illegal pattern'
}

To configure Check to report @since tags whose text does not match a digital version pattern (default tokens: types and methods). 


<module name="Checker">
  <module name="TreeWalker">
    <module name="IllegalBlockTag">
      <property name="tag" value="@since"/>
      <property name="tagTextPattern" value="^[1-9\\.]+$"/>
    </module>
  </module>
</module>

Example: 


/**
 * Some class
 * @since 1.1-beta
 */
public class Example3 {
  // violation 3 lines above 'Block tag 'since' is matched illegal pattern'
  /**
   * some doc
   * @todo remove
   * @since 1.1-beta
   */
  void testMethod1() {}
  // violation 3 lines above 'Block tag 'since' is matched illegal pattern'
  /**
   * some doc
   * @since 1.6
   */
  void testMethod2() {}

  /**
   * some doc
   * @todo later
   * @since 1.2
   */
  void testMethod3() {}

}

Same as Example 3, but only type tokens so method-level @since tags are ignored. 


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

Example: 


/**
 * Some class
 * @since 1.1-beta
 */
public class Example4 {
  // violation 3 lines above 'Block tag 'since' is matched illegal pattern'
  /**
   * some doc
   * @todo remove
   * @since 1.1-beta
   */
  void testMethod1() {}

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

  /**
   * some doc
   * @todo later
   * @since 1.2
   */
  void testMethod3() {}

}

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

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

Parent Module

TreeWalker