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

Class JavadocParagraphCheck

java.lang.Object
com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
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.
  • The outer most paragraph tags should not precede HTML block-tag. Nested paragraph tags are allowed to do that. This check only supports following block-tags: <address>,<blockquote> ,<div>,<dl> ,<h1>,<h2>,<h3>,<h4>,<h5>,<h6>,<hr> ,<ol>,<p>,<pre> ,<table>,<ul>.

ATTENTION:

This Check ignores HTML comments.

The Check ignores all the nested paragraph tags, it will not give any kind of violation if the paragraph tag is nested.

  • Property allowNewlineParagraph - Control whether the <p> tag should be placed immediately before the first word. Type is boolean. Default value is true.
  • 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.

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

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

  • Field Details

  • Constructor Details

  • 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.
      Since:
      6.9

    • 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.

    • isNestedParagraph

      private static boolean isNestedParagraph(DetailNode tag)
      Determines whether the paragraph tag is nested.
      Parameters:
      tag - html tag.
      Returns:
      true, if the paragraph tag is nested.

    • findFollowedBlockTagName

      @Nullable private static String findFollowedBlockTagName(DetailNode tag)
      Determines whether or not the paragraph tag is followed by block tag.
      Parameters:
      tag - html tag.
      Returns:
      block tag if the paragraph tag is followed by block tag or null if not found.

    • findFirstHtmlElementAfter

      @Nullable private static DetailNode findFirstHtmlElementAfter(DetailNode tag)
      Finds and returns first html element after the tag.
      Parameters:
      tag - html tag.
      Returns:
      first html element after the paragraph tag or null if not found.

    • getHtmlElementName

      @Nullable private static String getHtmlElementName(DetailNode htmlElement)
      Finds and returns first block-level html element name.
      Parameters:
      htmlElement - block-level html tag.
      Returns:
      block-level html element name or null if not found.

    • 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.

    • isImmediatelyFollowedByNewLine

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

    • getNextSibling

      private static DetailNode getNextSibling(DetailNode tag)
      Custom getNextSibling method to handle different types of paragraph tag. It works for both <p> and <p></p> tags.
      Parameters:
      tag - HTML_ELEMENT tag.
      Returns:
      next sibling of the tag.