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

Class JavadocNoErrorInThrowsTagCheck

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

All Implemented Interfaces:

Configurable, Contextualizable

public class JavadocNoErrorInThrowsTagCheck
extends AbstractJavadocCheck

Checks that Error types are not documented in @throws or @exception Javadoc tags.

Per the documentation comments style guide, errors generally should not be documented because they are unpredictable. This check reports documented throwable names whose simple name ends with Error, unless the same Error type is explicitly thrown with throw new in the documented method or constructor.

Since:

14.1.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
static final String	MSG_KEY	A key is pointing to the warning message text in "messages.properties" file.
private final Set<String>	thrownTypeNames	Type names explicitly thrown in the current documented construct.

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
JavadocNoErrorInThrowsTagCheck()	Creates a new JavadocNoErrorInThrowsTagCheck instance.

Method Summary

Modifier and Type	Method	Description
private void	collectThrownErrorType(DetailAST throwAst)	Collects type name from a throw new statement.
private void	collectThrownErrorTypes(DetailAST ast)	Collects type names explicitly thrown by throw new in a construct.
int[]	getDefaultJavadocTokens()	Returns the default javadoc token types a check is interested in.
int[]	getDefaultTokens()	Returns the default token a check is interested in.
int[]	getRequiredJavadocTokens()	The javadoc tokens that this check must be registered for.
final int[]	getRequiredTokens()	The tokens that this check must be registered for.
private static String	getSimpleName(String className)	Gets simple class name.
private static String	getTagName(DetailNode ast)	Gets the Javadoc tag name from a throws or exception block tag.
private static boolean	isErrorType(String className)	Checks whether class name is an Error type name.
private boolean	isExplicitlyThrown(String className)	Checks whether Error type is explicitly thrown in current documented construct.
private static boolean	isInIgnoreBlock(DetailAST constructAst, DetailAST throwAst)	Checks if a 'throw' usage is contained within a block that should be ignored.
void	visitJavadocToken(DetailNode ast)	Called to process a Javadoc token.
void	visitToken(DetailAST ast)	Called to process a token.

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

acceptJavadocWithNonTightHtml, beginJavadocTree, beginTree, destroy, finishJavadocTree, getAcceptableJavadocTokens, getAcceptableTokens, getBlockCommentAst, init, isCommentNodesRequired, leaveJavadocToken, log, setJavadocTokens, setViolateExecutionOnNonTightHtml

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

clearViolations, finishTree, 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_KEY

public static final String MSG_KEY

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

See Also:

• Constant Field Values

thrownTypeNames

private final Set<String> thrownTypeNames

Type names explicitly thrown in the current documented construct.

Constructor Details

JavadocNoErrorInThrowsTagCheck

public JavadocNoErrorInThrowsTagCheck()

Creates a new JavadocNoErrorInThrowsTagCheck instance.

Method Details

getDefaultTokens

public int[] getDefaultTokens()

Description copied from class: AbstractCheck

Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.

Overrides:

getDefaultTokens in class AbstractJavadocCheck

Returns:

the default tokens

See Also:

• TokenTypes

getRequiredTokens

public final int[] getRequiredTokens()

Description copied from class: AbstractCheck

The tokens that this check must be registered for.

Overrides:

getRequiredTokens in class AbstractJavadocCheck

Returns:

the token set this must be registered for.

See Also:

• TokenTypes

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

visitToken

public void visitToken(DetailAST ast)

Description copied from class: AbstractCheck

Called to process a token.

Overrides:

visitToken in class AbstractJavadocCheck

Parameters:

ast - the token to process

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

collectThrownErrorTypes

private void collectThrownErrorTypes(DetailAST ast)

Collects type names explicitly thrown by throw new in a construct.

Parameters:

ast - documented construct

collectThrownErrorType

private void collectThrownErrorType(DetailAST throwAst)

Collects type name from a throw new statement.

Parameters:

throwAst - throw statement

isInIgnoreBlock

private static boolean isInIgnoreBlock(DetailAST constructAst,
 DetailAST throwAst)

Checks if a 'throw' usage is contained within a block that should be ignored. Such blocks consist of try (with catch) blocks, local classes, anonymous classes, and lambda expressions. Note that a try block without catch is not considered.

Parameters:

constructAst - DetailAST node representing the documented construct

throwAst - DetailAST node representing the 'throw' literal

Returns:

true if throwAst is inside a block that should be ignored

isErrorType

private static boolean isErrorType(String className)

Checks whether class name is an Error type name.

Parameters:

className - class name

Returns:

true if class name is an Error type name

isExplicitlyThrown

private boolean isExplicitlyThrown(String className)

Checks whether Error type is explicitly thrown in current documented construct.

Parameters:

className - class name

Returns:

true if Error type is explicitly thrown in current documented construct

getSimpleName

private static String getSimpleName(String className)

Gets simple class name.

Parameters:

className - class name

Returns:

simple class name

getTagName

private static String getTagName(DetailNode ast)

Gets the Javadoc tag name from a throws or exception block tag.

Parameters:

ast - throws or exception block tag

Returns:

tag name with leading at sign