Class SingleLineJavadocCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable

    public class SingleLineJavadocCheck
    extends AbstractJavadocCheck
    Checks that a JavaDoc block can fit on a single line and doesn't contain at-clauses. Javadoc comment that contains at least one at-clause should be formatted in a few lines.
    All inline at-clauses are ignored by default.

    The Check has the following properties:
    ignoredTags - allows to specify a list of at-clauses (including custom at-clauses) to be ignored by the check.
    ignoreInlineTags - whether inline at-clauses must be ignored.

    Default configuration:

     <module name="SingleLineJavadoc"/>
     
    To specify a list of ignored at-clauses and make inline at-clauses not ignored in general:
     <module name="SingleLineJavadoc">
         <property name="ignoredTags" value="@inheritDoc, @link"/>
         <property name="ignoreInlineTags" value="false"/>
     </module>
     
    • Field Detail

      • MSG_KEY

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

        private java.util.List<java.lang.String> ignoredTags
        Allows to specify a list of tags to be ignored by check.
      • ignoreInlineTags

        private boolean ignoreInlineTags
        Whether inline tags must be ignored.
    • Constructor Detail

      • SingleLineJavadocCheck

        public SingleLineJavadocCheck()
    • Method Detail

      • setIgnoredTags

        public void setIgnoredTags​(java.lang.String... tags)
        Sets a list of tags to be ignored by check.
        Parameters:
        tags - to be ignored by check.
      • setIgnoreInlineTags

        public void setIgnoreInlineTags​(boolean ignoreInlineTags)
        Sets whether inline tags must be ignored.
        Parameters:
        ignoreInlineTags - whether inline tags must be ignored.
      • isSingleLineJavadoc

        private static boolean isSingleLineJavadoc​(DetailAST blockCommentStart)
        Checks if comment is single line comment.
        Parameters:
        blockCommentStart - the AST tree in which a block comment starts
        Returns:
        true, if comment is single line comment.
      • hasJavadocTags

        private boolean hasJavadocTags​(DetailNode javadocRoot)
        Checks if comment has javadoc tags which are not ignored. Also works on custom tags. As block tags can be interpreted only at the beginning of a line, only the first instance is checked.
        Parameters:
        javadocRoot - javadoc root node.
        Returns:
        true, if comment has javadoc tags which are not ignored.
        See Also:
        Block and inline tags
      • hasJavadocInlineTags

        private boolean hasJavadocInlineTags​(DetailNode javadocRoot)
        Checks if comment has in-line tags which are not ignored.
        Parameters:
        javadocRoot - javadoc root node.
        Returns:
        true, if comment has in-line tags which are not ignored.
        See Also:
        JavadocTags
      • isTagIgnored

        private boolean isTagIgnored​(DetailNode javadocTagSection)
        Checks if list of ignored tags contains javadocTagSection's javadoc tag.
        Parameters:
        javadocTagSection - to check javadoc tag in.
        Returns:
        true, if ignoredTags contains javadocTagSection's javadoc tag.