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 {@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.

Note: For defining a summary, both the first sentence and the @summary tag approaches are supported.

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