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

    • Field Detail

      • MSG_BLOCK_TAG_LOCATION

        public static final java.lang.String MSG_BLOCK_TAG_LOCATION
        A key is pointing to the warning message text in "messages.properties" file.
        See Also:
        Constant Field Values

    • Constructor Detail

      • JavadocBlockTagLocationCheck

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

    • Method Detail

      • setTags

        public final void setTags​(java.lang.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:
        JavadocTokenTypes

      • 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:
        JavadocTokenTypes