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

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="SummaryJavadocCheck"/>
  </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="SummaryJavadocCheck">
      <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="SummaryJavadocCheck">
      <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

• Google Style
• Checkstyle Style

Violation Messages

• javadoc.missed.html.close
• javadoc.parse.rule.error
• javadoc.unclosedHtml
• javadoc.wrong.singleton.html.tag
• summary.first.sentence
• summary.javaDoc
• summary.javaDoc.missing
• summary.javaDoc.missing.period

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