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
    • Method Detail

      • 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:
        SeverityLevel
      • 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:
        TokenTypes
      • 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:
        MessageFormat