Class SummaryJavadocCheck
- All Implemented Interfaces:
Configurable
,Contextualizable
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 isboolean
. Default value isfalse
. -
Property
forbiddenSummaryFragments
- Specify the regexp for forbidden summary fragments. Type isjava.util.regex.Pattern
. Default value is"^$"
. -
Property
period
- Specify the period symbol at the end of first javadoc sentence. Type isjava.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
FieldsModifier and TypeFieldDescriptionSet of allowed Tokens tags in summary java doc.private Pattern
Specify the regexp for forbidden summary fragments.private static final Pattern
This regexp is used to remove html tags, whitespace, and asterisks from a string.private static final Pattern
This regexp is used to convert multiline javadoc to single line without stars.static final String
A key is pointing to the warning message text in "messages.properties" file.static final String
A key is pointing to the warning message text in "messages.properties" file.static final String
A key is pointing to the warning message text in "messages.properties" file.static final String
A key is pointing to the warning message text in "messages.properties" file.private String
Specify the period symbol at the end of first javadoc sentence.private static final String
Period literal.private static final Pattern
This regexp is used to extract the content of a summary javadoc tag.private static final String
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 -
Method Summary
Modifier and TypeMethodDescriptionprivate boolean
containsForbiddenFragment
(String firstSentence) Tests if first sentence contains forbidden summary fragment.private static boolean
containsSummaryTag
(DetailNode javadoc) Checks if summary tag present.int[]
Returns the default javadoc token types a check is interested in.private static String
Finds and returns first sentence.private String
Gets entire content of summary tag.private static DetailNode
Returns an inline javadoc tag node that is within a html tag.int[]
The javadoc tokens that this check must be registered for.private static String
getStringInsideTag
(String result, DetailNode detailNode) Get concatenated string within text of html tags.private static String
Finds and returns summary sentence.private static String
getVisibleContent
(String summary) Gets the string that is visible to user in javadoc.private static boolean
Checks if the inline tag node is present.private static boolean
isPeriodAtEnd
(String sentence, 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
(Pattern pattern) Setter to specify the regexp for forbidden summary fragments.void
Setter to specify the period symbol at the end of first javadoc sentence.private static boolean
Checks if the node starts with an {@inheritDoc}.private static String
trimExcessWhitespaces
(String text) Trims the giventext
of duplicate whitespaces.private void
Checks the inline summary (if present) forperiod
at end and forbidden fragments.void
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
-
Field Details
-
MSG_SUMMARY_FIRST_SENTENCE
A key is pointing to the warning message text in "messages.properties" file.- See Also:
-
MSG_SUMMARY_JAVADOC
A key is pointing to the warning message text in "messages.properties" file.- See Also:
-
MSG_SUMMARY_JAVADOC_MISSING
A key is pointing to the warning message text in "messages.properties" file.- See Also:
-
MSG_SUMMARY_MISSING_PERIOD
A key is pointing to the warning message text in "messages.properties" file.- See Also:
-
JAVADOC_MULTILINE_TO_SINGLELINE_PATTERN
This regexp is used to convert multiline javadoc to single line without stars. -
HTML_ELEMENTS
This regexp is used to remove html tags, whitespace, and asterisks from a string. -
SUMMARY_PATTERN
This regexp is used to extract the content of a summary javadoc tag. -
PERIOD
Period literal.- See Also:
-
SUMMARY_TEXT
Summary tag text.- See Also:
-
ALLOWED_TYPES
Set of allowed Tokens tags in summary java doc. -
forbiddenSummaryFragments
Specify the regexp for forbidden summary fragments. -
period
Specify the period symbol at the end of first javadoc sentence.
-
-
Constructor Details
-
SummaryJavadocCheck
public SummaryJavadocCheck()
-
-
Method Details
-
setForbiddenSummaryFragments
Setter to specify the regexp for forbidden summary fragments.- Parameters:
pattern
- a pattern.
-
setPeriod
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 classAbstractJavadocCheck
- 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 classAbstractJavadocCheck
- Returns:
- the javadoc token set this must be registered for.
- See Also:
-
visitJavadocToken
Description copied from class:AbstractJavadocCheck
Called to process a Javadoc token.- Specified by:
visitJavadocToken
in classAbstractJavadocCheck
- Parameters:
ast
- the token to process
-
containsSummaryTag
Checks if summary tag present.- Parameters:
javadoc
- javadoc root node.- Returns:
true
if first sentence contains @summary tag.
-
isInlineTagPresent
Checks if the inline tag node is present.- Parameters:
ast
- ast node to check.- Returns:
- true, if the inline tag node is present.
-
getInlineTagNodeWithinHtmlElement
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
Checks if the first tag inside ast is summary tag.- Parameters:
javadoc
- root node.- Returns:
true
if first tag is summary tag.
-
validateSummaryTag
Checks the inline summary (if present) forperiod
at end and forbidden fragments.- Parameters:
ast
- javadoc root node.
-
getInlineSummary
Gets entire content of summary tag.- Returns:
- summary sentence of javadoc root node.
-
getVisibleContent
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
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
Tests if first sentence contains forbidden summary fragment.- Parameters:
firstSentence
- string with first sentence.- Returns:
true
if first sentence contains forbidden summary fragment.
-
trimExcessWhitespaces
Trims the giventext
of duplicate whitespaces.- Parameters:
text
- the text to transform.- Returns:
- the finalized form of the text.
-
startsWithInheritDoc
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
Finds and returns summary sentence.- Parameters:
ast
- javadoc root node.- Returns:
- violation string.
-
getStringInsideTag
Get concatenated string within text of html tags.- Parameters:
result
- javadoc stringdetailNode
- javadoc tag node- Returns:
- java doc tag content appended in result
-
getFirstSentence
Finds and returns first sentence.- Parameters:
ast
- Javadoc root node.- Returns:
- first sentence.
-