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. Check also violate Javadoc that does not contain first sentence.

    • 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 "";
   }
 }

    To ensure that summary do 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() {
   }
 }

    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
    Since:
    6.0

    • Field Detail

      • MSG_SUMMARY_FIRST_SENTENCE

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

      • MSG_SUMMARY_JAVADOC

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

      • MSG_SUMMARY_JAVADOC_MISSING

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

    • Constructor Detail

      • SummaryJavadocCheck

        public SummaryJavadocCheck()

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