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

Class 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

    • Method Detail

      • 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

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

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