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

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.

  • 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

  • Field Details

  • Constructor Details

  • 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

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

    • isDefinedFirst

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

    • isTextPresentInsideHtmlTag

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

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

    • isSummaryTag

      private static boolean isSummaryTag(DetailNode javadocInlineTag)
      Checks if the javadoc inline tag is {@summary} tag.
      Parameters:
      javadocInlineTag - node of type JavadocTokenTypes.JAVADOC_INLINE_TAG
      Returns:
      true if inline tag is summary tag.

    • isInlineReturnTag

      private static boolean isInlineReturnTag(DetailNode javadocInlineTag)
      Checks if the first tag inside ast is {@return} tag.
      Parameters:
      javadocInlineTag - node of type JavadocTokenTypes.JAVADOC_INLINE_TAG
      Returns:
      true if first tag is return tag.

    • isInlineTagWithName

      private static boolean isInlineTagWithName(DetailNode javadocInlineTag, 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.

    • validateSummaryTag

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

    • validateInlineReturnTag

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

    • 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

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