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:


/**
 * &#64;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:


/**
 * Escaped tag &#64;version (OK)
 * Plain text with {@code @see} (OK)
 * A @custom tag (OK)
 *
 */

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>

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