Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class JavadocBlockTagLocationCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public class JavadocBlockTagLocationCheck
extends AbstractJavadocCheck

    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.

    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.
  */
    • Property tags - Specify the javadoc tags to process. Type is java.lang.String[]. Default value is author, deprecated, exception, hidden, param, provides, return, see, serial, serialData, serialField, since, throws, uses, version.
    • Property violateExecutionOnNonTightHtml - Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Type is boolean. Default value is false.

    To configure the default check: 

     <module name="JavadocBlockTagLocation"/>

    Example: 

     /**
  * Escaped tag &#64;version (OK)
  * Plain text with {@code @see} (OK)
  * A @custom tag (OK)
  * 
  * email@author (OK)
  * (@param in parentheses) (OK)
  * '@param in single quotes' (OK)
  * @since 1.0 (OK)
  * text @return (violation)
  * * @param (violation)
 +* @serial (violation)
  * @see first (OK) @see second (violation)
  */
 public int field;

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

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

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

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

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • javadoc.blockTagLocation
    • javadoc.missed.html.close
    • javadoc.parse.rule.error
    • javadoc.wrong.singleton.html.tag
    Since:
    8.24