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

Class SummaryJavadocCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable
    public class SummaryJavadocCheck
extends AbstractJavadocCheck
    Checks that Javadoc summary sentence does not contain phrases that are not recommended to use. Summaries that contain only the {@inheritDoc} tag are skipped. Summaries that contain a non-empty {@return} are allowed. Check also violate Javadoc that does not contain first sentence, though with {@return} a period is not required as the Javadoc tool adds it.
    • Property forbiddenSummaryFragments - Specify the regexp for forbidden summary fragments. Type is java.util.regex.Pattern. Default value is "^$".
    • Property period - Specify the period symbol. Used to check the first sentence ends with a period. Periods that are not followed by a whitespace character are ignored (eg. the period in v1.0). Because some periods include whitespace built into the character, if this is set to a non-default value any period will end the sentence, whether it is followed by whitespace or not. Type is java.lang.String. Default value is ".".
    • 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.parse.rule.error
    • javadoc.unclosedHtml
    • javadoc.wrong.singleton.html.tag
    • summary.first.sentence
    • summary.javaDoc
    • summary.javaDoc.missing
    • summary.javaDoc.missing.period
    Since:
    6.0

    • Method Detail

      • setForbiddenSummaryFragments

        public void setForbiddenSummaryFragments​(Pattern pattern)
        Setter to specify the regexp for forbidden summary fragments.
        Parameters:
        pattern - a pattern.
        Since:
        6.0

      • setPeriod

        public void setPeriod​(String period)
        Setter to specify the period symbol. Used to check the first sentence ends with a period. Periods that are not followed by a whitespace character are ignored (eg. the period in v1.0). Because some periods include whitespace built into the character, if this is set to a non-default value any period will end the sentence, whether it is followed by whitespace or not.
        Parameters:
        period - period's value.
        Since:
        6.2

      • validateUntaggedSummary

        private void validateUntaggedSummary​(DetailNode ast)
        Checks the javadoc text for period at end and forbidden fragments.
        Parameters:
        ast - the javadoc text node

      • getInlineTagNode

        private static Optional<DetailNode> getInlineTagNode​(DetailNode javadoc)
        Gets the node for the inline tag if present.
        Parameters:
        javadoc - javadoc root node.
        Returns:
        the node for the inline tag if present.

      • isInlineTagPresent

        private static boolean isInlineTagPresent​(DetailNode ast)
        Checks if the inline tag node is present.
        Parameters:
        ast - ast node to check.
        Returns:
        true, if the inline tag node is present.

      • getInlineTagNodeForAst

        private static DetailNode getInlineTagNodeForAst​(DetailNode ast)
        Returns an inline javadoc tag node that is within a html tag.
        Parameters:
        ast - html tag node.
        Returns:
        inline summary javadoc tag node or null if no node is found.

      • getContentOfInlineCustomTag

        public static String getContentOfInlineCustomTag​(DetailNode inlineTag)
        Gets the content of inline custom tag.
        Parameters:
        inlineTag - inline tag node.
        Returns:
        String consisting of the content of inline custom tag.

      • extractInlineTagContent

        private static void extractInlineTagContent​(DetailNode node,
                                            StringBuilder customTagContent)
        Extracts the content of inline custom tag recursively.
        Parameters:
        node - DetailNode
        customTagContent - content of custom tag

      • getVisibleContent

        private static String getVisibleContent​(String summary)
        Gets the string that is visible to user in javadoc.
        Parameters:
        summary - entire content of summary javadoc.
        Returns:
        string that is visible to user in javadoc.

      • containsForbiddenFragment

        private boolean containsForbiddenFragment​(String firstSentence)
        Tests if first sentence contains forbidden summary fragment.
        Parameters:
        firstSentence - string with first sentence.
        Returns:
        true if first sentence contains forbidden summary fragment.

      • trimExcessWhitespaces

        private static String trimExcessWhitespaces​(String text)
        Trims the given text of duplicate whitespaces.
        Parameters:
        text - the text to transform.
        Returns:
        the finalized form of the text.

      • startsWithInheritDoc

        private static boolean startsWithInheritDoc​(DetailNode root)
        Checks if the node starts with an {@inheritDoc}.
        Parameters:
        root - the root node to examine.
        Returns:
        true if the javadoc starts with an {@inheritDoc}.

      • getSummarySentence

        private static String getSummarySentence​(DetailNode ast)
        Finds and returns summary sentence.
        Parameters:
        ast - javadoc root node.
        Returns:
        violation string.

      • getStringInsideTag

        private static String getStringInsideTag​(String result,
                                         DetailNode detailNode)
        Get concatenated string within text of html tags.
        Parameters:
        result - javadoc string
        detailNode - javadoc tag node
        Returns:
        java doc tag content appended in result

      • getFirstSentenceOrNull

        @Nullable
private static String getFirstSentenceOrNull​(DetailNode ast,
                                             String period)
        Finds and returns the first sentence.
        Parameters:
        ast - The Javadoc root node.
        period - The configured period symbol.
        Returns:
        The first sentence up to and excluding the period, or null if no ending was found.

      • streamTextParts

        private static Stream<String> streamTextParts​(DetailNode node)
        Streams through all the text under the given node.
        Parameters:
        node - The Javadoc node to examine.
        Returns:
        All the text in all nodes that have no child nodes.

      • findSentenceEndingOrNull

        @Nullable
private static String findSentenceEndingOrNull​(String text,
                                               String period)
        Finds the end of a sentence. If a sentence ending period was found, returns the whole string up to and excluding that period. The end of sentence detection here could be replaced in the future by Java's built-in BreakIterator class.
        Parameters:
        text - The string to search.
        period - The period character to find.
        Returns:
        The string up to and excluding the period, or null if no ending was found.