Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class SummaryJavadocCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

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

Since:

6.0

Nested Class Summary

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

AbstractAutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	DEFAULT_PERIOD	Default period literal.
private Pattern	forbiddenSummaryFragments	Specify the regexp for forbidden summary fragments.
private static final Pattern	HTML_ELEMENTS	This regexp is used to remove html tags, whitespace, and asterisks from a string.
private static final Pattern	JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN	This regexp is used to convert multiline javadoc to single-line without stars.
static final String	MSG_SUMMARY_FIRST_SENTENCE	A key is pointing to the warning message text in "messages.properties" file.
static final String	MSG_SUMMARY_JAVADOC	A key is pointing to the warning message text in "messages.properties" file.
static final String	MSG_SUMMARY_JAVADOC_MISSING	A key is pointing to the warning message text in "messages.properties" file.
static final String	MSG_SUMMARY_MISSING_PERIOD	A key is pointing to the warning message text in "messages.properties" file.
private String	period	Specify the period symbol.
private boolean	shouldValidateUntaggedSummary	Whether to validate untagged summary text in Javadoc.

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

MSG_JAVADOC_PARSE_RULE_ERROR, MSG_KEY_UNCLOSED_HTML_TAG

Constructor Summary

Constructors

Constructor	Description
SummaryJavadocCheck()

Method Summary

Modifier and Type	Method	Description
private boolean	containsForbiddenFragment(String firstSentence)	Tests if first sentence contains forbidden summary fragment.
private static Optional<String>	findSentenceEnding(String text, String period)	Finds the end of a sentence.
static String	getContentOfInlineCustomTag(DetailNode descriptionNode)	Gets the content of inline custom tag.
int[]	getDefaultJavadocTokens()	Returns the default javadoc token types a check is interested in.
private static Optional<String>	getFirstSentence(DetailNode ast, String period)	Finds the first sentence.
int[]	getRequiredJavadocTokens()	The javadoc tokens that this check must be registered for.
private static String	getStringInsideHtmlTag(String result, DetailNode detailNode)	Get concatenated string within text of html tags.
private static String	getSummarySentence(DetailNode ast)	Finds and returns summary sentence.
private static String	getVisibleContent(String summary)	Gets the string that is visible to user in javadoc.
private static boolean	isDefinedFirst(DetailNode inlineTagNode)	Whether the {@summary} tag is defined first in the javadoc.
static boolean	isHtmlTagWithoutText(DetailNode node)	Whether some text is present inside the HTML element or tag.
private static boolean	isInlineReturnTag(DetailNode javadocInlineTag)	Checks if the given node is an inline return node.
private static boolean	isSummaryTag(DetailNode javadocInlineTag)	Checks if the given node is an inline summary tag.
void	leaveJavadocToken(DetailNode ast)	Called after all the child nodes have been process.
void	setForbiddenSummaryFragments(Pattern pattern)	Setter to specify the regexp for forbidden summary fragments.
void	setPeriod(String period)	Setter to specify the period symbol.
private static boolean	startsWithInheritDoc(DetailNode root)	Checks if the node starts with an {@inheritDoc}.
private static Stream<String>	streamTextParts(DetailNode node)	Streams through all the text under the given node.
private static String	trimExcessWhitespaces(String text)	Trims the given text of duplicate whitespaces.
private void	validateInlineReturnTag(DetailNode inlineReturnTag)	Checks the inline return for forbidden fragments.
private void	validateSummaryTag(DetailNode inlineSummaryTag)	Checks the inline summary (if present) for period at end and forbidden fragments.
private void	validateUntaggedSummary(DetailNode ast)	Checks the javadoc text 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, setJavadocTokens, setViolateExecutionOnNonTightHtml, visitToken

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

clearViolations, getFileContents, getFilePath, 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.AbstractAutomaticBean

configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object

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

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

MSG_SUMMARY_MISSING_PERIOD

public static final 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 Pattern JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN

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

HTML_ELEMENTS

private static final Pattern HTML_ELEMENTS

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

DEFAULT_PERIOD

private static final String DEFAULT_PERIOD

Default period literal.

See Also:

• Constant Field Values

forbiddenSummaryFragments

private Pattern forbiddenSummaryFragments

Specify the regexp for forbidden summary fragments.

period

private String 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.

shouldValidateUntaggedSummary

private boolean shouldValidateUntaggedSummary

Whether to validate untagged summary text in Javadoc.

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.

Since:

6.0

setPeriod

public void setPeriod(String period)

Setter to 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.

Parameters:

period - period's value.

Since:

6.2

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:

• JavadocCommentsTokenTypes

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:

• JavadocCommentsTokenTypes

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

leaveJavadocToken

public void leaveJavadocToken(DetailNode ast)

Description copied from class: AbstractJavadocCheck

Called after all the child nodes have been process.

Overrides:

leaveJavadocToken in class AbstractJavadocCheck

Parameters:

ast - the token leaving

validateUntaggedSummary

private void validateUntaggedSummary(DetailNode ast)

Checks the javadoc text for period at end and forbidden fragments.

Parameters:

ast - the javadoc text node

isDefinedFirst

private static boolean isDefinedFirst(DetailNode inlineTagNode)

Whether the {@summary} tag is defined first in the javadoc.

Parameters:

inlineTagNode - node of type JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG

Returns:

true if the {@summary} tag is defined first in the javadoc

isHtmlTagWithoutText

public static boolean isHtmlTagWithoutText(DetailNode node)

Whether some text is present inside the HTML element or tag.

Parameters:

node - DetailNode of type JavadocCommentsTokenTypes.HTML_ELEMENT

Returns:

true if some text is present inside the HTML element

isSummaryTag

private static boolean isSummaryTag(DetailNode javadocInlineTag)

Checks if the given node is an inline summary tag.

Parameters:

javadocInlineTag - node

Returns:

true if inline tag is of type JavadocCommentsTokenTypes.SUMMARY_INLINE_TAG

isInlineReturnTag

private static boolean isInlineReturnTag(DetailNode javadocInlineTag)

Checks if the given node is an inline return node.

Parameters:

javadocInlineTag - node

Returns:

true if inline tag is of type JavadocCommentsTokenTypes.RETURN_INLINE_TAG

validateSummaryTag

private void validateSummaryTag(DetailNode inlineSummaryTag)

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

Parameters:

inlineSummaryTag - node of type JavadocCommentsTokenTypes.SUMMARY_INLINE_TAG

validateInlineReturnTag

private void validateInlineReturnTag(DetailNode inlineReturnTag)

Checks the inline return for forbidden fragments.

Parameters:

inlineReturnTag - node of type JavadocCommentsTokenTypes.RETURN_INLINE_TAG

getContentOfInlineCustomTag

public static String getContentOfInlineCustomTag(DetailNode descriptionNode)

Gets the content of inline custom tag.

Parameters:

descriptionNode - node of type JavadocCommentsTokenTypes.DESCRIPTION

Returns:

String consisting of the content of inline custom tag.

getVisibleContent

private static String getVisibleContent(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.

containsForbiddenFragment

private boolean containsForbiddenFragment(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 String trimExcessWhitespaces(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 String getSummarySentence(DetailNode ast)

Finds and returns summary sentence.

Parameters:

ast - javadoc root node.

Returns:

violation string.

getStringInsideHtmlTag

private static String getStringInsideHtmlTag(String result,
 DetailNode detailNode)

Get concatenated string within text of html tags.

Parameters:

result - javadoc string

detailNode - htmlContent node

Returns:

java doc tag content appended in result

getFirstSentence

private static Optional<String> getFirstSentence(DetailNode ast,
 String period)

Finds the first sentence.

Parameters:

ast - The Javadoc root node.

period - The configured period symbol.

Returns:

An Optional containing the first sentence up to and excluding the period, or an empty Optional if no ending was found.

streamTextParts

private static Stream<String> streamTextParts(DetailNode node)

Streams through all the text under the given node.

Parameters:

node - The Javadoc node to examine.

Returns:

All the text in all nodes that have no child nodes.

findSentenceEnding

private static Optional<String> findSentenceEnding(String text,
 String period)

Finds the end of a sentence. The end of sentence detection here could be replaced in the future by Java's built-in BreakIterator class.

Parameters:

text - The string to search.

period - The period character to find.

Returns:

An Optional containing the string up to and excluding the period, or empty Optional if no ending was found.