Class JavadocTypeCheck
- 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.JavadocTypeCheck
-
- All Implemented Interfaces:
Configurable
,Contextualizable
public class JavadocTypeCheck extends AbstractCheck
Checks the Javadoc of a type.Does not perform checks for author and version tags for inner classes, as they should be redundant because of outer class.
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
allowMissingParamTags
Controls whether to ignore errors when a method has type parameters but does not have matching param tags in the javadoc.private boolean
allowUnknownTags
Controls whether to flag errors for unknown tags.private java.util.regex.Pattern
authorFormat
Compiled regexp to match author tag content.private static java.lang.String
CLOSE_ANGLE_BRACKET
Close angle bracket literal.private Scope
excludeScope
The visibility scope where Javadoc comments shouldn't be checked.static java.lang.String
MSG_JAVADOC_MISSING
A key is pointing to the warning message text in "messages.properties" file.static java.lang.String
MSG_MISSING_TAG
A key is pointing to the warning message text in "messages.properties" file.static java.lang.String
MSG_TAG_FORMAT
A key is pointing to the warning message text in "messages.properties" file.static java.lang.String
MSG_UNKNOWN_TAG
A key is pointing to the warning message text in "messages.properties" file.static java.lang.String
MSG_UNUSED_TAG
A key is pointing to the warning message text in "messages.properties" file.static java.lang.String
MSG_UNUSED_TAG_GENERAL
A key is pointing to the warning message text in "messages.properties" file.private static java.lang.String
OPEN_ANGLE_BRACKET
Open angle bracket literal.private Scope
scope
The scope to check for.private static java.util.regex.Pattern
TYPE_NAME_IN_JAVADOC_TAG
Pattern to match type name within angle brackets in javadoc param tag.private static java.util.regex.Pattern
TYPE_NAME_IN_JAVADOC_TAG_SPLITTER
Pattern to split type name field in javadoc param tag.private java.util.regex.Pattern
versionFormat
Compiled regexp to match version tag content.
-
Constructor Summary
Constructors Constructor Description JavadocTypeCheck()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description private void
checkTag(int lineNo, java.util.List<JavadocTag> tags, java.lang.String tagName, java.util.regex.Pattern formatPattern)
Verifies that a type definition has a required tag.private void
checkTypeParamTag(int lineNo, java.util.List<JavadocTag> tags, java.lang.String typeParamName)
Verifies that a type definition has the specified param tag for the specified type parameter name.private void
checkUnusedTypeParamTags(java.util.List<JavadocTag> tags, java.util.List<java.lang.String> typeParamNames)
Checks for unused param tags for type parameters.private static java.lang.String
extractTypeParamNameFromTag(JavadocTag tag)
Extracts type parameter name from tag.int[]
getAcceptableTokens()
The configurable token set.int[]
getDefaultTokens()
Returns the default token a check is interested in.private java.util.List<JavadocTag>
getJavadocTags(TextBlock textBlock)
Gets all standalone tags from a given javadoc.int[]
getRequiredTokens()
The tokens that this check must be registered for.void
setAllowMissingParamTags(boolean flag)
Controls whether to allow a type which has type parameters to omit matching param tags in the javadoc.void
setAllowUnknownTags(boolean flag)
Controls whether to flag errors for unknown tags.void
setAuthorFormat(java.util.regex.Pattern pattern)
Set the author tag pattern.void
setExcludeScope(Scope excludeScope)
Set the excludeScope.void
setScope(Scope scope)
Sets the scope to check.void
setVersionFormat(java.util.regex.Pattern pattern)
Set the version format pattern.private boolean
shouldCheck(DetailAST ast)
Whether we should check this node.void
visitToken(DetailAST ast)
Called to process a token.-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck
beginTree, destroy, finishTree, getClassLoader, getFileContents, getLine, getLines, getTabWidth, getTokenNames, init, isCommentNodesRequired, 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
-
-
-
-
Field Detail
-
MSG_JAVADOC_MISSING
public static final java.lang.String MSG_JAVADOC_MISSING
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_UNKNOWN_TAG
public static final java.lang.String MSG_UNKNOWN_TAG
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_TAG_FORMAT
public static final java.lang.String MSG_TAG_FORMAT
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_MISSING_TAG
public static final java.lang.String MSG_MISSING_TAG
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_UNUSED_TAG
public static final java.lang.String MSG_UNUSED_TAG
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_UNUSED_TAG_GENERAL
public static final java.lang.String MSG_UNUSED_TAG_GENERAL
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
OPEN_ANGLE_BRACKET
private static final java.lang.String OPEN_ANGLE_BRACKET
Open angle bracket literal.- See Also:
- Constant Field Values
-
CLOSE_ANGLE_BRACKET
private static final java.lang.String CLOSE_ANGLE_BRACKET
Close angle bracket literal.- See Also:
- Constant Field Values
-
TYPE_NAME_IN_JAVADOC_TAG
private static final java.util.regex.Pattern TYPE_NAME_IN_JAVADOC_TAG
Pattern to match type name within angle brackets in javadoc param tag.
-
TYPE_NAME_IN_JAVADOC_TAG_SPLITTER
private static final java.util.regex.Pattern TYPE_NAME_IN_JAVADOC_TAG_SPLITTER
Pattern to split type name field in javadoc param tag.
-
scope
private Scope scope
The scope to check for.
-
excludeScope
private Scope excludeScope
The visibility scope where Javadoc comments shouldn't be checked.
-
authorFormat
private java.util.regex.Pattern authorFormat
Compiled regexp to match author tag content.
-
versionFormat
private java.util.regex.Pattern versionFormat
Compiled regexp to match version tag content.
-
allowMissingParamTags
private boolean allowMissingParamTags
Controls whether to ignore errors when a method has type parameters but does not have matching param tags in the javadoc. Defaults to false.
-
allowUnknownTags
private boolean allowUnknownTags
Controls whether to flag errors for unknown tags. Defaults to false.
-
-
Method Detail
-
setScope
public void setScope(Scope scope)
Sets the scope to check.- Parameters:
scope
- a scope.
-
setExcludeScope
public void setExcludeScope(Scope excludeScope)
Set the excludeScope.- Parameters:
excludeScope
- a scope.
-
setAuthorFormat
public void setAuthorFormat(java.util.regex.Pattern pattern)
Set the author tag pattern.- Parameters:
pattern
- a pattern.
-
setVersionFormat
public void setVersionFormat(java.util.regex.Pattern pattern)
Set the version format pattern.- Parameters:
pattern
- a pattern.
-
setAllowMissingParamTags
public void setAllowMissingParamTags(boolean flag)
Controls whether to allow a type which has type parameters to omit matching param tags in the javadoc. Defaults to false.- Parameters:
flag
- aBoolean
value
-
setAllowUnknownTags
public void setAllowUnknownTags(boolean flag)
Controls whether to flag errors for unknown tags. Defaults to false.- Parameters:
flag
- aBoolean
value
-
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.- Specified by:
getDefaultTokens
in classAbstractCheck
- Returns:
- the default tokens
- See Also:
TokenTypes
-
getAcceptableTokens
public int[] getAcceptableTokens()
Description copied from class:AbstractCheck
The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.- Specified by:
getAcceptableTokens
in classAbstractCheck
- Returns:
- the token set this check is designed for.
- See Also:
TokenTypes
-
getRequiredTokens
public int[] getRequiredTokens()
Description copied from class:AbstractCheck
The tokens that this check must be registered for.- Specified by:
getRequiredTokens
in classAbstractCheck
- Returns:
- the token set this must be registered for.
- See Also:
TokenTypes
-
visitToken
public void visitToken(DetailAST ast)
Description copied from class:AbstractCheck
Called to process a token.- Overrides:
visitToken
in classAbstractCheck
- Parameters:
ast
- the token to process
-
shouldCheck
private boolean shouldCheck(DetailAST ast)
Whether we should check this node.- Parameters:
ast
- a given node.- Returns:
- whether we should check a given node.
-
getJavadocTags
private java.util.List<JavadocTag> getJavadocTags(TextBlock textBlock)
Gets all standalone tags from a given javadoc.- Parameters:
textBlock
- the Javadoc comment to process.- Returns:
- all standalone tags from the given javadoc.
-
checkTag
private void checkTag(int lineNo, java.util.List<JavadocTag> tags, java.lang.String tagName, java.util.regex.Pattern formatPattern)
Verifies that a type definition has a required tag.- Parameters:
lineNo
- the line number for the type definition.tags
- tags from the Javadoc comment for the type definition.tagName
- the required tag name.formatPattern
- regexp for the tag value.
-
checkTypeParamTag
private void checkTypeParamTag(int lineNo, java.util.List<JavadocTag> tags, java.lang.String typeParamName)
Verifies that a type definition has the specified param tag for the specified type parameter name.- Parameters:
lineNo
- the line number for the type definition.tags
- tags from the Javadoc comment for the type definition.typeParamName
- the name of the type parameter
-
checkUnusedTypeParamTags
private void checkUnusedTypeParamTags(java.util.List<JavadocTag> tags, java.util.List<java.lang.String> typeParamNames)
Checks for unused param tags for type parameters.- Parameters:
tags
- tags from the Javadoc comment for the type definition.typeParamNames
- names of type parameters
-
extractTypeParamNameFromTag
private static java.lang.String extractTypeParamNameFromTag(JavadocTag tag)
Extracts type parameter name from tag.- Parameters:
tag
- javadoc tag to extract parameter name- Returns:
- extracts type parameter name from tag
-
-