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
  • Field Details

    • MSG_BLOCK_TAG_LOCATION

      public static final String MSG_BLOCK_TAG_LOCATION
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
  • Constructor Details

    • JavadocBlockTagLocationCheck

      public JavadocBlockTagLocationCheck()
      Creates a new JavadocBlockTagLocationCheck instance with default settings.
  • Method Details

    • setTags

      public final void setTags(String... values)
      Setter to specify the javadoc tags to process.
      Parameters:
      values - user's values.
    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      The javadoc tokens that this check must be registered for. According to the specs each block tag must appear at the beginning of a line, otherwise it will be interpreted as a plain text. This check looks for a block tag in the javadoc text, thus it needs the TEXT tokens.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:
    • getAcceptableJavadocTokens

      public int[] getAcceptableJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The configurable javadoc token set. Used to protect Checks against malicious users who specify an unacceptable javadoc token set in the configuration file. The default implementation returns the check's default javadoc tokens.
      Overrides:
      getAcceptableJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this check is designed for.
      See Also:
    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:
    • visitJavadocToken

      public void visitJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process