Class WriteTagCheck

All Implemented Interfaces:
Configurable, Contextualizable

public class WriteTagCheck extends AbstractCheck

Requires user defined Javadoc tag to be present in Javadoc comment with defined format. To define the format for a tag, set property tagFormat to a regular expression. Property tagSeverity is used for severity of events when the tag exists.

  • Property tag - Specify the name of tag. Type is java.lang.String. Default value is null.
  • Property tagFormat - Specify the regexp to match tag content. Type is java.util.regex.Pattern. Default value is null.
  • Property tagSeverity - Specify the severity level when tag is found and printed. Type is com.puppycrawl.tools.checkstyle.api.SeverityLevel. Default value is info.
  • Property tokens - tokens to check Type is java.lang.String[]. Validation type is tokenSet. Default value is: INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF.

Example of default Check configuration that do nothing.

 <module name="WriteTag"/>
 

Example:

 /**
 * Some class
 */
 public class Test {
   /** some doc */
   void foo() {}
 }
 

To configure Check to demand some special tag (for example &#64;since) to be present on classes javadoc.

 <module name="WriteTag">
   <property name="tag" value="@since"/>
 </module>
 

Example:

 /**
 * Some class
 */
 public class Test { // violation as required tag is missed
   /** some doc */
   void foo() {} // OK, as methods are not checked by default
 }
 

To configure Check to demand some special tag (for example &#64;since) to be present on method javadocs also in addition to default tokens.

 <module name="WriteTag">
   <property name="tag" value="@since"/>
   <property name="tokens"
          value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF, METHOD_DEF" />
 </module>
 

Example:

 /**
 * Some class
 */
 public class Test { // violation as required tag is missed
   /** some doc */
   void foo() {} // violation as required tag is missed
 }
 

To configure Check to demand &#64;since tag to be present with digital value on method javadocs also in addition to default tokens. Attention: usage of non "ignore" in tagSeverity will print violation with such severity on each presence of such tag.

 <module name="WriteTag">
   <property name="tag" value="@since"/>
   <property name="tokens"
          value="INTERFACE_DEF, CLASS_DEF, ENUM_DEF, ANNOTATION_DEF, RECORD_DEF, METHOD_DEF" />
   <property name="tagFormat" value="[1-9\.]"/>
   <property name="tagSeverity" value="ignore"/>
 </module>
 

Example:

 /**
 * Some class
 * @since 1.2
 */
 public class Test {
   /** some doc
   * @since violation
   */
   void foo() {}
 }
 

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

  • javadoc.writeTag
  • type.missingTag
  • type.tagFormat
Since:
4.2
  • Field Details

    • MSG_MISSING_TAG

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

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

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

      private Pattern tagRegExp
      Compiled regexp to match tag.
    • tagFormat

      private Pattern tagFormat
      Specify the regexp to match tag content.
    • tag

      private String tag
      Specify the name of tag.
    • tagSeverity

      private SeverityLevel tagSeverity
      Specify the severity level when tag is found and printed.
  • Constructor Details

    • WriteTagCheck

      public WriteTagCheck()
  • Method Details

    • setTag

      public void setTag(String tag)
      Setter to specify the name of tag.
      Parameters:
      tag - tag to check
    • setTagFormat

      public void setTagFormat(Pattern pattern)
      Setter to specify the regexp to match tag content.
      Parameters:
      pattern - a String value
    • setTagSeverity

      public final void setTagSeverity(SeverityLevel severity)
      Setter to specify the severity level when tag is found and printed.
      Parameters:
      severity - The new severity level
      See Also:
    • getDefaultTokens

      public int[] getDefaultTokens()
      Description copied from class: AbstractCheck
      Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.
      Specified by:
      getDefaultTokens in class AbstractCheck
      Returns:
      the default tokens
      See Also:
    • getAcceptableTokens

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

      public int[] getRequiredTokens()
      Description copied from class: AbstractCheck
      The tokens that this check must be registered for.
      Specified by:
      getRequiredTokens in class AbstractCheck
      Returns:
      the token set this must be registered for.
      See Also:
    • visitToken

      public void visitToken(DetailAST ast)
      Description copied from class: AbstractCheck
      Called to process a token.
      Overrides:
      visitToken in class AbstractCheck
      Parameters:
      ast - the token to process
    • checkTag

      private void checkTag(int lineNo, String... comment)
      Verifies that a type definition has a required tag.
      Parameters:
      lineNo - the line number for the type definition.
      comment - the Javadoc comment for the type definition.
    • logTag

      private void logTag(int line, String tagName, String tagValue)
      Log a message.
      Parameters:
      line - the line number where the violation was found
      tagName - the javadoc tag to be logged
      tagValue - the contents of the tag
      See Also: