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