Class SummaryJavadocCheck

All Implemented Interfaces:
Configurable, Contextualizable

public class SummaryJavadocCheck extends AbstractJavadocCheck

Checks that Javadoc summary sentence does not contain phrases that are not recommended to use. Summaries that contain only the {@inheritDoc} tag are skipped. Check also violate Javadoc that does not contain first sentence.

  • Property violateExecutionOnNonTightHtml - Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. Type is boolean. Default value is false.
  • Property forbiddenSummaryFragments - Specify the regexp for forbidden summary fragments. Type is java.util.regex.Pattern. Default value is "^$".
  • Property period - Specify the period symbol at the end of first javadoc sentence. Type is java.lang.String. Default value is ".".

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

 <module name="SummaryJavadocCheck"/>
 

Example of {@inheritDoc} without summary.

 public class Test extends Exception {
 //Valid
   /**
    * {@inheritDoc}
    */
   public String ValidFunction(){
     return "";
   }
   //Violation
   /**
    *
    */
   public String InvalidFunction(){
     return "";
   }
 }
 

To ensure that summary do not contain phrase like "This method returns", use following config:

 <module name="SummaryJavadocCheck">
   <property name="forbiddenSummaryFragments"
     value="^This method returns.*"/>
 </module>
 

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

 <module name="SummaryJavadocCheck">
   <property name="period" value="。"/>
 </module>
 

Example of period property.

 public class TestClass {
   /**
   * This is invalid java doc.
   */
   void invalidJavaDocMethod() {
   }
   /**
   * This is valid java doc。
   */
   void validJavaDocMethod() {
   }
 }
 

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

  • javadoc.missed.html.close
  • javadoc.parse.rule.error
  • javadoc.wrong.singleton.html.tag
  • summary.first.sentence
  • summary.javaDoc
  • summary.javaDoc.missing
Since:
6.0
  • Field Details

    • MSG_SUMMARY_FIRST_SENTENCE

      public static final String MSG_SUMMARY_FIRST_SENTENCE
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
    • MSG_SUMMARY_JAVADOC

      public static final String MSG_SUMMARY_JAVADOC
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
    • MSG_SUMMARY_JAVADOC_MISSING

      public static final String MSG_SUMMARY_JAVADOC_MISSING
      A key is pointing to the warning message text in "messages.properties" file.
      See Also:
  • Constructor Details

    • SummaryJavadocCheck

      public SummaryJavadocCheck()
  • Method Details

    • setForbiddenSummaryFragments

      public void setForbiddenSummaryFragments(Pattern pattern)
      Setter to specify the regexp for forbidden summary fragments.
      Parameters:
      pattern - a pattern.
    • setPeriod

      public void setPeriod(String period)
      Setter to specify the period symbol at the end of first javadoc sentence.
      Parameters:
      period - period's value.
    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:
    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The javadoc tokens that this check must be registered for.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:
    • visitJavadocToken

      public void visitJavadocToken(DetailNode ast)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      ast - the token to process