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 {
  // violation below, 'Summary javadoc is missing'
  /** */
  public String withoutJavadoc() { return ""; }

  /**
   * {@summary  }
   */
  public String withJavadoc() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'

  /**
   * {@summary This is a java doc with dot period.}
   */
  public void withPeriod() {}

  /**
   * {@summary This is a java doc with ideographic period。}
   */
  public void withoutPeriod() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
   * This method returns nothing.
   */
  void withDotPeriod() {}

  /**
   * This method returns nothing。
   */
  void withoutDotPeriod() {}
  // violation 4 lines above 'First sentence of Javadoc is missing an ending period'
}

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 {
  // violation below, 'Summary javadoc is missing'
  /** */
  public String withoutJavadoc() { return ""; }

  /**
   * {@summary  }
   */
  public String withJavadoc() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'

  /**
   * {@summary This is a java doc with dot period.}
   */
  public void withPeriod() {}

  /**
   * {@summary This is a java doc with ideographic period。}
   */
  public void withoutPeriod() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
   * This method returns nothing.
   */
  void withDotPeriod() {}
  // violation 4 lines above 'Forbidden summary fragment'
  /**
   * This method returns nothing。
   */
  void withoutDotPeriod() {}
  // violation 4 lines above 'First sentence of Javadoc is missing an ending period'
}

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 {
  // violation below, 'Summary javadoc is missing'
  /** */
  public String withoutJavadoc() { return ""; }

  /**
   * {@summary  }
   */
  public String withJavadoc() { return ""; }
  // violation 3 lines above 'Summary javadoc is missing'

  /**
   * {@summary This is a java doc with dot period.}
   */
  public void withPeriod() {}
  // violation 3 lines above 'Summary of Javadoc is missing an ending period'
  /**
   * {@summary This is a java doc with ideographic period。}
   */
  public void withoutPeriod() {}

  /**
   * This method returns nothing.
   */
  void withDotPeriod() {}
  // violation 4 lines above 'First sentence of Javadoc is missing an ending period'
  /**
   * This method returns nothing。
   */
  void withoutDotPeriod() {}

}

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.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.SummaryJavadocCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

TreeWalker