GitHub Twitter Stackoverflow GoogleGroups JProfiler

JavadocBlockTagLocation

Since Checkstyle 8.24

Description

Checks that a javadoc block tag appears only at the beginning of a line, ignoring leading asterisks and white space. A block tag is a token that starts with @ symbol and is preceded by a whitespace. This check ignores block tags in comments and inside inline tags {@code } and {@literal }.

Rationale: according to the specification all javadoc block tags should be placed at the beginning of a line. Tags that are not placed at the beginning are treated as plain text. To recognize intentional tag placement to text area it is better to escape the @ symbol, and all non-escaped tags should be located at the beginning of the line. See NOTE section for details on how to escape.

Notes

To place a tag explicitly as text, escape the @ symbol with HTML entity @ or place it inside {@code }, for example: 


/**
 * @serial literal in {@code @serial} Javadoc tag.
 */

Properties

name description type default value since
tags Specify the javadoc tags to process. String[] author, deprecated, exception, hidden, param, provides, return, see, serial, serialData, serialField, since, throws, uses, version 8.24
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 8.24

Examples

To configure the default check: 


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

Example:


class Example1 {
  /**
   * Escaped tag &#64;version (OK)
   * Plain text with {@code @see} (OK)
   * A @custom tag (OK)
   * Some text with misplaced @version tag
   */
  void foo1() {}
  // violation 3 lines above 'block tag '@version' should be placed at the beginning'
  /**
   * Another misplaced tag: text @noinspection here
   */
  void foo2() {}

  /**
   * @return properly placed tag (OK)
   */
  int foo3() {
    return 0;
  }
}

To configure the check to verify tags from JEP 8068562 only: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocBlockTagLocation">
      <property name="tags" value="apiNote, implSpec, implNote"/>
    </module>
  </module>
</module>

Example:


class Example2 {
  /**
   * Escaped tag &#64;version (OK)
   * Plain text with {@code @see} (OK)
   * A @custom tag (OK)
   * Some text with misplaced @version tag
   */
  void foo1() {}

  /**
   * Another misplaced tag: text @noinspection here
   */
  void foo2() {}

  /**
   * @return properly placed tag (OK)
   */
  int foo3() {
    return 0;
  }
}

To configure the check to verify all default tags and some custom tags in addition: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocBlockTagLocation">
      <!-- default tags -->
      <property name="tags" value="author, deprecated, exception, hidden"/>
      <property name="tags" value="param, provides, return, see, serial"/>
      <property name="tags" value="serialData, serialField, since, throws"/>
      <property name="tags" value="uses, version"/>
      <!-- additional tags used in the project -->
      <property name="tags" value="noinspection"/>
    </module>
  </module>
</module>

Example:


class Example3 {
  /**
   * Escaped tag &#64;version (OK)
   * Plain text with {@code @see} (OK)
   * A @custom tag (OK)
   * Some text with misplaced @version tag
   */
  void foo1() {}
  // violation 3 lines above 'block tag '@version' should be placed at the beginning'
  /**
   * Another misplaced tag: text @noinspection here
   */
  void foo2() {}
  // violation 3 lines above 'should be placed at the beginning'
  /**
   * @return properly placed tag (OK)
   */
  int foo3() {
    return 0;
  }
}

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

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

Parent Module

TreeWalker