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 at the end of first javadoc sentence. 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​(java.util.regex.Pattern pattern)
        Setter to specify the regexp for forbidden summary fragments.
        Parameters:
        pattern - a pattern.
        Since:
        6.0

      • setPeriod

        public void setPeriod​(java.lang.String period)
        Setter to specify the period symbol at the end of first javadoc sentence.
        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 java.util.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.

      • isInlineTagWithName

        private static boolean isInlineTagWithName​(DetailNode javadocInlineTag,
                                           java.lang.String name)
        Checks if the first tag inside ast is a tag with the given name.
        Parameters:
        javadocInlineTag - node of type JavadocTokenTypes.JAVADOC_INLINE_TAG
        name - name of inline tag.
        Returns:
        true if first tag is a tag with the given name.

      • getContentOfInlineCustomTag

        public static java.lang.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,
                                            java.lang.StringBuilder customTagContent)
        Extracts the content of inline custom tag recursively.
        Parameters:
        node - DetailNode
        customTagContent - content of custom tag

      • getVisibleContent

        private static java.lang.String getVisibleContent​(java.lang.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​(java.lang.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 java.lang.String trimExcessWhitespaces​(java.lang.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 java.lang.String getSummarySentence​(DetailNode ast)
        Finds and returns summary sentence.
        Parameters:
        ast - javadoc root node.
        Returns:
        violation string.

      • getStringInsideTag

        private static java.lang.String getStringInsideTag​(java.lang.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

      • getFirstSentence

        private static java.lang.String getFirstSentence​(DetailNode ast)
        Finds and returns first sentence.
        Parameters:
        ast - Javadoc root node.
        Returns:
        first sentence.