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>

Example1: 

class Example1 {

  /**
   * {@inheritDoc}
   */
  public String m1(){ return ""; }
  // violation below, 'Summary javadoc is missing'
  /** */
  public String m2(){ return ""; }

  /**
   * {@summary  }
   */
  public String m3(){ return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p> <p/>}
   */
  public String m4() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p>This is a javadoc with period.<p/>}
   */
  public void m5() {}

  /**
   * This method returns nothing.
   */
  void m6() {}

  /**
  * {@summary This is a java doc with period symbol。}
  */
  public void m7() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
  * {@summary First sentence is normally the summary.
  * Use of html tags:
  * <ul>
  * <li>Item one.</li>
  * <li>Item two.</li>
  * </ul>}
  */
  public void m8() {}

}

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>

Example2: 

class Example2 {

  /**
   * {@inheritDoc}
   */
  public String m1(){ return ""; }
  // violation below, 'Summary javadoc is missing'
  /** */
  public String m2(){ return ""; }

  /**
   * {@summary  }
   */
  public String m3(){ return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p> <p/>}
   */
  public String m4() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p>This is a javadoc with period.<p/>}
   */
  public void m5() {}

  /**
   * This method returns nothing.
   */
  void m6() {}
  // violation 4 lines above 'Forbidden summary fragment'
  /**
  * {@summary This is a java doc with period symbol。}
  */
  public void m7() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
  * {@summary First sentence is normally the summary.
  * Use of html tags:
  * <ul>
  * <li>Item one.</li>
  * <li>Item two.</li>
  * </ul>}
  */
  public void m8() {}

}

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>

Example3: 

class Example3 {

  /**
   * {@inheritDoc}
   */
  public String m1(){ return ""; }
  // violation below, 'Summary javadoc is missing'
  /** */
  public String m2(){ return ""; }

  /**
   * {@summary  }
   */
  public String m3(){ return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p> <p/>}
   */
  public String m4() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'
  /**
   * {@summary <p>This is a javadoc with period.<p/>}
   */
  public void m5() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
   * This method returns nothing.
   */
  void m6() {}
  // violation 4 lines above 'First sentence of Javadoc is missing an ending period'
  /**
  * {@summary This is a java doc without period。}
  */
  public void m7() {}

  /**
  * {@summary First sentence is normally the summary。
  * Use of html tags:
  * <ul>
  * <li>Item one.</li>
  * <li>Item two.</li>
  * </ul>}
  */
  public void m8() {}
  // violation 8 lines above 'Summary of Javadoc is missing an ending period'
}

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