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

    To configure the default check to validate that first sentence is not empty and first sentence is not missing: 

     <module name="SummaryJavadocCheck"/>

    Example of {@inheritDoc} without summary. 

     public class Test extends Exception {
 //Valid
   /**
    * {@inheritDoc}
    */
   public String ValidFunction(){
     return "";
   }
   //Violation
   /**
    *
    */
   public String InvalidFunction(){
     return "";
   }
 }

    Example of non permitted empty javadoc for Inline Summary Javadoc. 

     public class Test extends Exception {
   /**
    * {@summary  }
    */
   public String InvalidFunctionOne(){ // violation
     return "";
   }

   /**
    * {@summary <p> <p/>}
    */
   public String InvalidFunctionTwo(){ // violation
     return "";
   }

   /**
    * {@summary <p>This is summary for validFunctionThree.<p/>}
    */
   public void validFunctionThree(){} // ok
 }

    To ensure that summary does not contain phrase like "This method returns", use following config: 

     <module name="SummaryJavadocCheck">
   <property name="forbiddenSummaryFragments"
     value="^This method returns.*"/>
 </module>

    To specify period symbol at the end of first javadoc sentence: 

     <module name="SummaryJavadocCheck">
   <property name="period" value="。"/>
 </module>

    Example of period property. 

     public class TestClass {
  /**
   * This is invalid java doc.
   */
   void invalidJavaDocMethod() {
   }
  /**
   * This is valid java doc。
   */
   void validJavaDocMethod() {
   }
 }

    Example of period property for inline summary javadoc. 

     public class TestClass {
  /**
   * {@summary This is invalid java doc.}
   */
   public void invalidJavaDocMethod() { // violation
   }
  /**
   * {@summary This is valid java doc。}
   */
   public void validJavaDocMethod() { // ok
   }
 }

    Example of inline summary javadoc with HTML tags. 

     public class Test {
  /**
   * {@summary First sentence is normally the summary.
   * Use of html tags:
   * <ul>
   * <li>Item one.</li>
   * <li>Item two.</li>
   * </ul>}
   */
   public void validInlineJavadoc() { // ok
   }
 }

    Parent is com.puppycrawl.tools.checkstyle.TreeWalker

    Violation Message Keys:

    • javadoc.missed.html.close
    • javadoc.parse.rule.error
    • 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.

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

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

      • getInlineTagNodeWithinHtmlElement

        private static DetailNode getInlineTagNodeWithinHtmlElement​(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.

      • isPeriodNotAtEnd

        private static boolean isPeriodNotAtEnd​(java.lang.String sentence,
                                        java.lang.String period)
        Checks if the string does not end with period.
        Parameters:
        sentence - string to check for period at end.
        period - string to check within sentence.
        Returns:
        true if sentence does not end with period.

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