Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class JavadocParagraphCheck

java.lang.Object
com.puppycrawl.tools.checkstyle.api.AutomaticBean
com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
com.puppycrawl.tools.checkstyle.api.AbstractCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocParagraphCheck
All Implemented Interfaces:
Configurable, Contextualizable
public class JavadocParagraphCheck extends AbstractJavadocCheck

Checks the Javadoc paragraph.

Checks that:

  • There is one blank line between each of two paragraphs.
  • Each paragraph but the first has <p> immediately before the first word, with no space after.
  • 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.
  • Property allowNewlineParagraph - Control whether the <p> tag should be placed immediately before the first word. Type is boolean. Default value is true.

To configure the default check: 

 <module name="JavadocParagraph"/>

By default, the check will report a violation if there is a new line or whitespace after the <p> tag: 

 /**
  * No tag (ok).
  *
  * <p>Tag immediately before the text (ok).
  * <p>No blank line before the tag (violation).
  *
  * <p>
  * New line after tag (violation).
  *
  * <p> Whitespace after tag (violation).
  *
  */
 public class TestClass {
 }

To allow newlines and spaces immediately after the <p> tag: 

 <module name="JavadocParagraph">
   <property name="allowNewlineParagraph" value="false"/>
 </module>

In case of allowNewlineParagraph set to false the following example will not have any violations: 

 /**
  * No tag (ok).
  *
  * <p>Tag immediately before the text (ok).
  * <p>No blank line before the tag (violation).
  *
  * <p>
  * New line after tag (ok).
  *
  * <p> Whitespace after tag (ok).
  *
  */
 public class TestClass {
 }

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

  • javadoc.missed.html.close
  • javadoc.paragraph.line.before
  • javadoc.paragraph.misplaced.tag
  • javadoc.paragraph.redundant.paragraph
  • javadoc.paragraph.tag.after
  • javadoc.parse.rule.error
  • javadoc.wrong.singleton.html.tag
Since:
6.0

  • Field Details

    • MSG_TAG_AFTER

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

    • MSG_LINE_BEFORE

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

    • MSG_REDUNDANT_PARAGRAPH

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

    • MSG_MISPLACED_TAG

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

    • allowNewlineParagraph

      private boolean allowNewlineParagraph
      Control whether the <p> tag should be placed immediately before the first word.

  • Constructor Details

    • JavadocParagraphCheck

      public JavadocParagraphCheck()

  • Method Details

    • setAllowNewlineParagraph

      public void setAllowNewlineParagraph(boolean value)
      Setter to control whether the <p> tag should be placed immediately before the first word.
      Parameters:
      value - value to set.

    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:

    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The javadoc tokens that this check must be registered for.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:

    • visitJavadocToken

      public void visitJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process

    • checkEmptyLine

      private void checkEmptyLine(DetailNode newline)
      Determines whether or not the next line after empty line has paragraph tag in the beginning.
      Parameters:
      newline - NEWLINE node.

    • checkParagraphTag

      private void checkParagraphTag(DetailNode tag)
      Determines whether or not the line with paragraph tag has previous empty line.
      Parameters:
      tag - html tag.

    • getNearestNode

      private static DetailNode getNearestNode(DetailNode node)
      Returns nearest node.
      Parameters:
      node - DetailNode node.
      Returns:
      nearest node.

    • isEmptyLine

      private static boolean isEmptyLine(DetailNode newLine)
      Determines whether or not the line is empty line.
      Parameters:
      newLine - NEWLINE node.
      Returns:
      true, if line is empty line.

    • isFirstParagraph

      private static boolean isFirstParagraph(DetailNode paragraphTag)
      Determines whether or not the line with paragraph tag is first line in javadoc.
      Parameters:
      paragraphTag - paragraph tag.
      Returns:
      true, if line with paragraph tag is first line in javadoc.

    • getNearestEmptyLine

      private static DetailNode getNearestEmptyLine(DetailNode node)
      Finds and returns nearest empty line in javadoc.
      Parameters:
      node - DetailNode node.
      Returns:
      Some nearest empty line in javadoc.

    • isImmediatelyFollowedByText

      private static boolean isImmediatelyFollowedByText(DetailNode tag)
      Tests whether the paragraph tag is immediately followed by the text.
      Parameters:
      tag - html tag.
      Returns:
      true, if the paragraph tag is immediately followed by the text.