SummaryJavadoc

Since Checkstyle 6.0

Description

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 {@code {@return}} are allowed. Check also violate Javadoc that does not contain first sentence, though with {@code {@return}} a period is not required as the Javadoc tool adds it.

Properties

name description type default value since
forbiddenSummaryFragments Specify the regexp for forbidden summary fragments. Pattern "^$" 6.0
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. String "." 6.2
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. boolean false 8.3

Examples

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SummaryJavadoc"/>
  </module>
</module>

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="Checker">
  <module name="TreeWalker">
    <module name="SummaryJavadoc">
      <property name="forbiddenSummaryFragments"
        value="^This method returns.*"/>
    </module>
  </module>
</module>

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

<module name="Checker">
  <module name="TreeWalker">
    <module name="SummaryJavadoc">
      <property name="period" value="。"/>
    </module>
  </module>
</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
  }
}

Example of Usage

Violation Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker