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. By default Check validate that first sentence is not empty:

 <module name="SummaryJavadocCheck"/>
 

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 - use following config:

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

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.regex.Pattern	forbiddenSummaryFragments Regular expression for forbidden summary fragments.
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.
private java.lang.String	period Period symbol at the end of first javadoc sentence.
private static java.lang.String	PERIOD Period literal.
private static java.util.Set<java.lang.Integer>	SKIP_TOKENS Stores allowed values in document for inherit doc literal.

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, MSG_KEY_PARSE_ERROR, MSG_KEY_UNRECOGNIZED_ANTLR_ERROR

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.
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.
int[]	getRequiredJavadocTokens() The javadoc tokens that this check must be registered for.
private static boolean	isOnlyInheritDoc(DetailNode ast) Finds if inheritDoc is placed properly in java doc.
void	setForbiddenSummaryFragments(java.util.regex.Pattern pattern) Sets custom value of regular expression for forbidden summary fragments.
void	setPeriod(java.lang.String period) Sets value of period symbol at the end of first javadoc sentence.
void	visitJavadocToken(DetailNode ast) Called to process a Javadoc token.

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

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

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

destroy, getClassLoader, getFileContents, getLine, getLines, getTabWidth, getTokenNames, leaveToken, log, log, setClassLoader, setFileContents, setMessages, setTabWidth, setTokens

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

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

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

configure, contextualize, finishLocalSetup, 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

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.

PERIOD

private static final java.lang.String PERIOD

Period literal.

See Also:

Constant Field Values

SKIP_TOKENS

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

Stores allowed values in document for inherit doc literal.

forbiddenSummaryFragments

private java.util.regex.Pattern forbiddenSummaryFragments

Regular expression for forbidden summary fragments.

period

private java.lang.String period

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)

Sets custom value of regular expression for forbidden summary fragments.

Parameters:

pattern - a pattern.

setPeriod

public void setPeriod(java.lang.String period)

Sets value of 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

isOnlyInheritDoc

private static boolean isOnlyInheritDoc(DetailNode ast)

Finds if inheritDoc is placed properly in java doc.

Parameters:

ast - Javadoc root node.

Returns:

true if inheritDoc is valid or false.

getFirstSentence

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

Finds and returns first sentence.

Parameters:

ast - Javadoc root node.

Returns:

first sentence.

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.