com.puppycrawl.tools.checkstyle.checks.javadoc

Class SummaryJavadocCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.api.AutomaticBean

com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

com.puppycrawl.tools.checkstyle.api.AbstractCheck

com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

com.puppycrawl.tools.checkstyle.checks.javadoc.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 "";
   }
 }
 

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 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() {
   }
 }
 

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
   }
 }
 

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
• summary.javaDoc.missing.period

Since:

6.0

Nested Class Summary

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

AutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field and Description
private static java.util.Set<java.lang.Integer>	ALLOWED_TYPES Set of allowed Tokens tags in summary java doc.
private java.util.regex.Pattern	forbiddenSummaryFragments Specify the regexp for forbidden summary fragments.
private static java.util.regex.Pattern	HTML_ELEMENTS This regexp is used to remove html tags, whitespace, and asterisks from a string.
private static java.util.regex.Pattern	JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN This regexp is used to convert multiline javadoc to single line without stars.
static java.lang.String	MSG_SUMMARY_FIRST_SENTENCE A key is pointing to the warning message text in "messages.properties" file.
static java.lang.String	MSG_SUMMARY_JAVADOC A key is pointing to the warning message text in "messages.properties" file.
static java.lang.String	MSG_SUMMARY_JAVADOC_MISSING A key is pointing to the warning message text in "messages.properties" file.
static java.lang.String	MSG_SUMMARY_MISSING_PERIOD A key is pointing to the warning message text in "messages.properties" file.
private java.lang.String	period Specify the period symbol at the end of first javadoc sentence.
private static java.lang.String	PERIOD Period literal.
private static java.util.regex.Pattern	SUMMARY_PATTERN This regexp is used to extract the content of a summary javadoc tag.
private static java.lang.String	SUMMARY_TEXT Summary tag text.

Fields inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

MSG_JAVADOC_MISSED_HTML_CLOSE, MSG_JAVADOC_PARSE_RULE_ERROR, MSG_JAVADOC_WRONG_SINGLETON_TAG

Constructor Summary

Constructors

Constructor and Description
SummaryJavadocCheck()

Method Summary

Modifier and Type	Method and Description
private boolean	containsForbiddenFragment(java.lang.String firstSentence) Tests if first sentence contains forbidden summary fragment.
private static boolean	containsSummaryTag(DetailNode javadoc) Checks if summary tag present.
int[]	getDefaultJavadocTokens() Returns the default javadoc token types a check is interested in.
private static java.lang.String	getFirstSentence(DetailNode ast) Finds and returns first sentence.
private java.lang.String	getInlineSummary() Gets entire content of summary tag.
private static DetailNode	getInlineTagNodeWithinHtmlElement(DetailNode ast) Returns an inline javadoc tag node that is within a html tag.
int[]	getRequiredJavadocTokens() The javadoc tokens that this check must be registered for.
private static java.lang.String	getStringInsideTag(java.lang.String result, DetailNode detailNode) Get concatenated string within text of html tags.
private static java.lang.String	getSummarySentence(DetailNode ast) Finds and returns summary sentence.
private static java.lang.String	getVisibleContent(java.lang.String summary) Gets the string that is visible to user in javadoc.
private static boolean	isInlineTagPresent(DetailNode ast) Checks if the inline tag node is present.
private static boolean	isPeriodAtEnd(java.lang.String sentence, java.lang.String period) Checks if the string ends with period.
private static boolean	isSummaryTag(DetailNode javadoc) Checks if the first tag inside ast is summary tag.
void	setForbiddenSummaryFragments(java.util.regex.Pattern pattern) Setter to specify the regexp for forbidden summary fragments.
void	setPeriod(java.lang.String period) Setter to specify the period symbol at the end of first javadoc sentence.
private static boolean	startsWithInheritDoc(DetailNode root) Checks if the node starts with an {@inheritDoc}.
private static java.lang.String	trimExcessWhitespaces(java.lang.String text) Trims the given text of duplicate whitespaces.
private void	validateSummaryTag(DetailNode ast) Checks the inline summary (if present) for period at end and forbidden fragments.
void	visitJavadocToken(DetailNode ast) Called to process a Javadoc token.

Methods inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

acceptJavadocWithNonTightHtml, beginJavadocTree, beginTree, destroy, finishJavadocTree, finishTree, getAcceptableJavadocTokens, getAcceptableTokens, getBlockCommentAst, getDefaultTokens, getRequiredTokens, init, isCommentNodesRequired, leaveJavadocToken, setJavadocTokens, setViolateExecutionOnNonTightHtml, visitToken

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

clearViolations, getFileContents, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MSG_SUMMARY_FIRST_SENTENCE

public static final java.lang.String MSG_SUMMARY_FIRST_SENTENCE

A key is pointing to the warning message text in "messages.properties" file.

See Also:

Constant Field Values

MSG_SUMMARY_JAVADOC

public static final java.lang.String MSG_SUMMARY_JAVADOC

A key is pointing to the warning message text in "messages.properties" file.

See Also:

Constant Field Values

MSG_SUMMARY_JAVADOC_MISSING

public static final java.lang.String MSG_SUMMARY_JAVADOC_MISSING

A key is pointing to the warning message text in "messages.properties" file.

See Also:

Constant Field Values

MSG_SUMMARY_MISSING_PERIOD

public static final java.lang.String MSG_SUMMARY_MISSING_PERIOD

A key is pointing to the warning message text in "messages.properties" file.

See Also:

Constant Field Values

JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN

private static final java.util.regex.Pattern JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN

This regexp is used to convert multiline javadoc to single line without stars.

HTML_ELEMENTS

private static final java.util.regex.Pattern HTML_ELEMENTS

This regexp is used to remove html tags, whitespace, and asterisks from a string.

SUMMARY_PATTERN

private static final java.util.regex.Pattern SUMMARY_PATTERN

This regexp is used to extract the content of a summary javadoc tag.

PERIOD

private static final java.lang.String PERIOD

Period literal.

See Also:

Constant Field Values

SUMMARY_TEXT

private static final java.lang.String SUMMARY_TEXT

Summary tag text.

See Also:

Constant Field Values

ALLOWED_TYPES

private static final java.util.Set<java.lang.Integer> ALLOWED_TYPES

Set of allowed Tokens tags in summary java doc.

forbiddenSummaryFragments

private java.util.regex.Pattern forbiddenSummaryFragments

Specify the regexp for forbidden summary fragments.

period

private java.lang.String period

Specify the period symbol at the end of first javadoc sentence.

Constructor Detail

SummaryJavadocCheck

public SummaryJavadocCheck()

Method Detail

setForbiddenSummaryFragments

public void setForbiddenSummaryFragments(java.util.regex.Pattern pattern)

Setter to specify the regexp for forbidden summary fragments.

Parameters:

pattern - a pattern.

setPeriod

public void setPeriod(java.lang.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:

JavadocTokenTypes

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:

JavadocTokenTypes

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

containsSummaryTag

private static boolean containsSummaryTag(DetailNode javadoc)

Checks if summary tag present.

Parameters:

javadoc - javadoc root node.

Returns:

true if first sentence contains @summary tag.

isInlineTagPresent

private static boolean isInlineTagPresent(DetailNode ast)

Checks if the inline tag node is present.

Parameters:

ast - ast node to check.

Returns:

true, if the inline tag node is present.

getInlineTagNodeWithinHtmlElement

private static DetailNode getInlineTagNodeWithinHtmlElement(DetailNode ast)

Returns an inline javadoc tag node that is within a html tag.

Parameters:

ast - html tag node.

Returns:

inline summary javadoc tag node or null if no node is found.

isSummaryTag

private static boolean isSummaryTag(DetailNode javadoc)

Checks if the first tag inside ast is summary tag.

Parameters:

javadoc - root node.

Returns:

true if first tag is summary tag.

validateSummaryTag

private void validateSummaryTag(DetailNode ast)

Checks the inline summary (if present) for period at end and forbidden fragments.

Parameters:

ast - javadoc root node.

getInlineSummary

private java.lang.String getInlineSummary()

Gets entire content of summary tag.

Returns:

summary sentence of javadoc root node.

getVisibleContent

private static java.lang.String getVisibleContent(java.lang.String summary)

Gets the string that is visible to user in javadoc.

Parameters:

summary - entire content of summary javadoc.

Returns:

string that is visible to user in javadoc.

isPeriodAtEnd

private static boolean isPeriodAtEnd(java.lang.String sentence,
                                     java.lang.String period)

Checks if the string ends with period.

Parameters:

sentence - string to check for period at end.

period - string to check within sentence.

Returns:

true if sentence ends with period.

containsForbiddenFragment

private boolean containsForbiddenFragment(java.lang.String firstSentence)

Tests if first sentence contains forbidden summary fragment.

Parameters:

firstSentence - string with first sentence.

Returns:

true if first sentence contains forbidden summary fragment.

trimExcessWhitespaces

private static java.lang.String trimExcessWhitespaces(java.lang.String text)

Trims the given text of duplicate whitespaces.

Parameters:

text - the text to transform.

Returns:

the finalized form of the text.

startsWithInheritDoc

private static boolean startsWithInheritDoc(DetailNode root)

Checks if the node starts with an {@inheritDoc}.

Parameters:

root - the root node to examine.

Returns:

true if the javadoc starts with an {@inheritDoc}.

getSummarySentence

private static java.lang.String getSummarySentence(DetailNode ast)

Finds and returns summary sentence.

Parameters:

ast - javadoc root node.

Returns:

violation string.

getStringInsideTag

private static java.lang.String getStringInsideTag(java.lang.String result,
                                                   DetailNode detailNode)

Get concatenated string within text of html tags.

Parameters:

result - javadoc string

detailNode - javadoc tag node

Returns:

java doc tag content appended in result

getFirstSentence

private static java.lang.String getFirstSentence(DetailNode ast)

Finds and returns first sentence.

Parameters:

ast - Javadoc root node.

Returns:

first sentence.