Class RequireEmptyLineBeforeBlockTagGroupCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable

    public class RequireEmptyLineBeforeBlockTagGroupCheck
    extends AbstractJavadocCheck

    Checks that one blank line before the block tag if it is present in Javadoc.

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

     <module name="RequireEmptyLineBeforeBlockTagGroup"/>
     

    By default, the check will report a violation if there is no blank line before the block tag, like in the example below.

     /**
      * testMethod's javadoc.
      * @return something (violation)
      */
     public boolean testMethod() {
         return false;
     }
     

    Valid javadoc should have a blank line separating the parameters, return, throw, or other tags like in the example below.

      /**
      * testMethod's javadoc.
      *
      * @param firstParam
      * @return something
      */
      public boolean testMethod(int firstParam) {
          return false;
      }
      

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • javadoc.missed.html.close
    • javadoc.parse.rule.error
    • javadoc.tag.line.before
    • javadoc.wrong.singleton.html.tag
    Since:
    8.36
    • Field Detail

      • ONLY_TAG_VARIATION_1

        private static final List<Integer> ONLY_TAG_VARIATION_1
        Case when space separates the tag and the asterisk like in the below example.
          /**
           * @param noSpace there is no space here
         
      • ONLY_TAG_VARIATION_2

        private static final List<Integer> ONLY_TAG_VARIATION_2
        Case when no space separates the tag and the asterisk like in the below example.
          /**
           *@param noSpace there is no space here
         
    • Method Detail

      • isAnotherTagBefore

        private static boolean isAnotherTagBefore​(DetailNode tagNode)
        Returns true when there is a javadoc tag before the provided tagNode.
        Parameters:
        tagNode - the javadoc tag node, to look for more tags before it.
        Returns:
        true when there is a javadoc tag before the provided tagNode.
      • isOnlyTagInWholeJavadoc

        private static boolean isOnlyTagInWholeJavadoc​(DetailNode tagNode)
        Returns true when there are is only whitespace and asterisks before the provided tagNode. When javadoc has only a javadoc tag like @ in it, the JAVADOC_TAG in a JAVADOC detail node will always have 2 or 3 siblings before it. The parse tree looks like:
         JAVADOC[3x0]
         |--NEWLINE[3x0] : [\n]
         |--LEADING_ASTERISK[4x0] : [ *]
         |--WS[4x2] : [ ]
         |--JAVADOC_TAG[4x3] : [@param T The bar.\n ]
         
        Or it can also look like:
         JAVADOC[3x0]
         |--NEWLINE[3x0] : [\n]
         |--LEADING_ASTERISK[4x0] : [ *]
         |--JAVADOC_TAG[4x3] : [@param T The bar.\n ]
         
        We do not include the variation
          /**@param noSpace there is no space here
         
        which results in the tree
         JAVADOC[3x0]
         |--JAVADOC_TAG[4x3] : [@param noSpace there is no space here\n ]
         
        because this one is invalid. We must recommend placing a blank line to separate @param from the first javadoc asterisks.
        Parameters:
        tagNode - the at tag node to check if there is nothing before it
        Returns:
        true if there is no text before the tagNode
      • hasInsufficientConsecutiveNewlines

        private static boolean hasInsufficientConsecutiveNewlines​(DetailNode tagNode)
        Returns true when there are not enough empty lines before the provided tagNode.

        Iterates through the previous siblings of the tagNode looking for empty lines until there are no more siblings or it hits something other than asterisk, whitespace or newline. If it finds at least one empty line, return true. Return false otherwise.

        Parameters:
        tagNode - the tagNode to check if there are sufficient empty lines before it.
        Returns:
        true if there are not enough empty lines before the tagNode.