Class SummaryJavadocCheck

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

Note: For defining a summary, both the first sentence and the @summary tag approaches are supported.

Since:
6.0

  • Field Details

    • MSG_SUMMARY_FIRST_SENTENCE

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

    • MSG_SUMMARY_JAVADOC

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

    • MSG_SUMMARY_JAVADOC_MISSING

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

    • MSG_SUMMARY_MISSING_PERIOD

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

    • JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN

      private static final Pattern JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN
      This regexp is used to convert multiline javadoc to single-line without stars.

    • HTML_ELEMENTS

      private static final Pattern HTML_ELEMENTS
      This regexp is used to remove html tags, whitespace, and asterisks from a string.

    • DEFAULT_PERIOD

      private static final String DEFAULT_PERIOD
      Default period literal.
      See Also:

    • forbiddenSummaryFragments

      private Pattern forbiddenSummaryFragments
      Specify the regexp for forbidden summary fragments.

    • period

      private String 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.

    • shouldValidateUntaggedSummary

      private boolean shouldValidateUntaggedSummary
      Whether to validate untagged summary text in Javadoc.

  • Constructor Details

    • SummaryJavadocCheck

      public SummaryJavadocCheck()

  • Method Details

    • 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

    • 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

    • leaveJavadocToken

      public void leaveJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called after all the child nodes have been process.
      Overrides:
      leaveJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token leaving

    • validateUntaggedSummary

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

    • isDefinedFirst

      private static boolean isDefinedFirst(DetailNode inlineTagNode)
      Whether the {@summary} tag is defined first in the javadoc.
      Parameters:
      inlineTagNode - node of type JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG
      Returns:
      true if the {@summary} tag is defined first in the javadoc

    • isHtmlTagWithoutText

      public static boolean isHtmlTagWithoutText(DetailNode node)
      Whether some text is present inside the HTML element or tag.
      Parameters:
      node - DetailNode of type JavadocCommentsTokenTypes.HTML_ELEMENT
      Returns:
      true if some text is present inside the HTML element

    • isSummaryTag

      private static boolean isSummaryTag(DetailNode javadocInlineTag)
      Checks if the given node is an inline summary tag.
      Parameters:
      javadocInlineTag - node
      Returns:
      true if inline tag is of type JavadocCommentsTokenTypes.SUMMARY_INLINE_TAG

    • isInlineReturnTag

      private static boolean isInlineReturnTag(DetailNode javadocInlineTag)
      Checks if the given node is an inline return node.
      Parameters:
      javadocInlineTag - node
      Returns:
      true if inline tag is of type JavadocCommentsTokenTypes.RETURN_INLINE_TAG

    • validateSummaryTag

      private void validateSummaryTag(DetailNode inlineSummaryTag)
      Checks the inline summary (if present) for period at end and forbidden fragments.
      Parameters:
      inlineSummaryTag - node of type JavadocCommentsTokenTypes.SUMMARY_INLINE_TAG

    • validateInlineReturnTag

      private void validateInlineReturnTag(DetailNode inlineReturnTag)
      Checks the inline return for forbidden fragments.
      Parameters:
      inlineReturnTag - node of type JavadocCommentsTokenTypes.RETURN_INLINE_TAG

    • getContentOfInlineCustomTag

      public static String getContentOfInlineCustomTag(DetailNode descriptionNode)
      Gets the content of inline custom tag.
      Parameters:
      descriptionNode - node of type JavadocCommentsTokenTypes.DESCRIPTION
      Returns:
      String consisting of the content of inline 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.

    • getStringInsideHtmlTag

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

    • getFirstSentence

      private static Optional<String> getFirstSentence(DetailNode ast, String period)
      Finds the first sentence.
      Parameters:
      ast - The Javadoc root node.
      period - The configured period symbol.
      Returns:
      An Optional containing the first sentence up to and excluding the period, or an empty Optional 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.

    • findSentenceEnding

      private static Optional<String> findSentenceEnding(String text, String period)
      Finds the end of a sentence. 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:
      An Optional containing the string up to and excluding the period, or empty Optional if no ending was found.