public class JavadocMethodCheck extends AbstractTypeAwareCheck
Modifier and Type | Class and Description |
---|---|
private static class |
JavadocMethodCheck.ExceptionInfo
Stores useful information about declared exception.
|
AbstractTypeAwareCheck.AbstractClassInfo, AbstractTypeAwareCheck.Token
Modifier and Type | Field and Description |
---|---|
private java.util.List<java.lang.String> |
allowedAnnotations
List of annotations that could allow missed documentation.
|
private boolean |
allowMissingJavadoc
Controls whether to ignore errors when there is no javadoc.
|
private boolean |
allowMissingParamTags
Controls whether to ignore errors when a method has parameters but does
not have matching param tags in the javadoc.
|
private boolean |
allowMissingPropertyJavadoc
Controls whether to allow missing Javadoc on accessor methods for
properties (setters and getters).
|
private boolean |
allowMissingReturnTag
Controls whether to ignore errors when a method returns non-void type
but does not have a return tag in the javadoc.
|
private boolean |
allowMissingThrowsTags
Controls whether to ignore errors when a method declares that it throws
exceptions but does not have matching throws tags in the javadoc.
|
private boolean |
allowThrowsTagsForSubclasses
Controls whether to allow documented exceptions that are subclass of one
of declared exception.
|
private boolean |
allowUndeclaredRTE
Controls whether to allow documented exceptions that are not declared if
they are a subclass of java.lang.RuntimeException.
|
private static int |
DEFAULT_MIN_LINE_COUNT
Default value of minimal amount of lines in method to demand documentation presence.
|
private static java.lang.String |
END_JAVADOC
Multiline finished at end of comment.
|
private Scope |
excludeScope
The visibility scope where Javadoc comments shouldn't be checked.
|
private java.util.regex.Pattern |
ignoreMethodNamesRegex
Method names that match this pattern do not require javadoc blocks.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_ARG
Compiled regexp to match Javadoc tags that take an argument.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_ARG_MULTILINE_START
Compiled regexp to match first part of multilineJavadoc tags.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_MULTILINE_CONT
Compiled regexp to look for a continuation of the comment.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_NOARG
Compiled regexp to match Javadoc tags with no argument.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_NOARG_CURLY
Compiled regexp to match Javadoc tags with no argument and {}.
|
private static java.util.regex.Pattern |
MATCH_JAVADOC_NOARG_MULTILINE_START
Compiled regexp to match first part of multilineJavadoc tags.
|
private int |
minLineCount
Minimal amount of lines in method to demand documentation presence.
|
static java.lang.String |
MSG_CLASS_INFO
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_DUPLICATE_TAG
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_EXPECTED_TAG
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_INVALID_INHERIT_DOC
A key is pointing to the warning message text in "messages.properties"
file.
|
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_RETURN_EXPECTED
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 |
NEXT_TAG
Multiline finished at next Javadoc.
|
private Scope |
scope
The visibility scope where Javadoc comments are checked.
|
private boolean |
validateThrows
Allows validating throws tags.
|
Constructor and Description |
---|
JavadocMethodCheck() |
Modifier and Type | Method and Description |
---|---|
private static Scope |
calculateScope(DetailAST ast)
Returns the scope for the method/constructor at the specified AST.
|
private static int |
calculateTagColumn(java.util.regex.Matcher javadocTagMatcher,
int lineNumber,
int startColumnNumber)
Calculates column number using Javadoc tag matcher.
|
private void |
checkComment(DetailAST ast,
TextBlock comment)
Checks the Javadoc for a method.
|
private void |
checkParamTags(java.util.List<JavadocTag> tags,
DetailAST parent,
boolean reportExpectedTags)
Checks a set of tags for matching parameters.
|
private void |
checkReturnTag(java.util.List<JavadocTag> tags,
int lineNo,
boolean reportExpectedTags)
Checks for only one return tag.
|
private void |
checkThrowsTags(java.util.List<JavadocTag> tags,
java.util.List<JavadocMethodCheck.ExceptionInfo> throwsList,
boolean reportExpectedTags)
Checks a set of tags for matching throws.
|
int[] |
getAcceptableTokens()
The configurable token set.
|
int[] |
getDefaultTokens()
Returns the default token a check is interested in.
|
private static int |
getMethodsNumberOfLine(DetailAST methodDef)
Some javadoc.
|
private static java.util.List<JavadocTag> |
getMethodTags(TextBlock comment)
Returns the tags in a javadoc comment.
|
private static java.util.List<JavadocTag> |
getMultilineArgTags(java.util.regex.Matcher argMultilineStart,
int column,
java.lang.String[] lines,
int lineIndex,
int tagLine)
Gets multiline Javadoc tags with arguments.
|
private static java.util.List<JavadocTag> |
getMultilineNoArgTags(java.util.regex.Matcher noargMultilineStart,
java.lang.String[] lines,
int lineIndex,
int tagLine)
Gets multiline Javadoc tags with no arguments.
|
private static java.util.List<DetailAST> |
getParameters(DetailAST ast)
Computes the parameter nodes for a method.
|
private java.util.List<JavadocMethodCheck.ExceptionInfo> |
getThrows(DetailAST ast)
Computes the exception nodes for a method.
|
private boolean |
hasAllowedAnnotations(DetailAST methodDef)
Some javadoc.
|
private boolean |
hasShortCircuitTag(DetailAST ast,
java.util.List<JavadocTag> tags)
Validates whether the Javadoc has a short circuit tag.
|
boolean |
isCommentNodesRequired()
Whether comment nodes are required or not.
|
private boolean |
isContentsAllowMissingJavadoc(DetailAST ast)
Checks if the Javadoc can be missing if the method or constructor is
below the minimum line count or has a special annotation.
|
private boolean |
isInThrows(java.util.List<JavadocMethodCheck.ExceptionInfo> throwsList,
AbstractTypeAwareCheck.AbstractClassInfo documentedClassInfo,
java.util.Set<java.lang.String> foundThrows)
Verifies that documented exception is in throws.
|
protected boolean |
isMissingJavadocAllowed(DetailAST ast)
The JavadocMethodCheck is about to report a missing Javadoc.
|
protected void |
logLoadError(AbstractTypeAwareCheck.Token ident)
Logs error if unable to load class information.
|
private boolean |
matchesSkipRegex(DetailAST methodDef)
Checks if the given method name matches the regex.
|
protected void |
processAST(DetailAST ast)
Called to process an AST when visiting it.
|
private static boolean |
removeMatchingParam(java.util.List<DetailAST> params,
java.lang.String paramName)
Remove parameter from params collection by name.
|
private static boolean |
searchMatchingTypeParameter(java.util.List<DetailAST> typeParams,
java.lang.String requiredTypeName)
Returns true if required type found in type parameters.
|
void |
setAllowedAnnotations(java.lang.String... userAnnotations)
Sets list of annotations.
|
void |
setAllowMissingJavadoc(boolean flag)
Controls whether to ignore errors when there is no javadoc.
|
void |
setAllowMissingParamTags(boolean flag)
Controls whether to allow a method which has parameters to omit matching
param tags in the javadoc.
|
void |
setAllowMissingPropertyJavadoc(boolean flag)
Controls whether to ignore errors when there is no javadoc for a
property accessor (setter/getter methods).
|
void |
setAllowMissingReturnTag(boolean flag)
Controls whether to allow a method which returns non-void type to omit
the return tag in the javadoc.
|
void |
setAllowMissingThrowsTags(boolean flag)
Controls whether to allow a method which declares that it throws
exceptions to omit matching throws tags in the javadoc.
|
void |
setAllowThrowsTagsForSubclasses(boolean flag)
Controls whether to allow documented exception that are subclass of one
of declared exceptions.
|
void |
setAllowUndeclaredRTE(boolean flag)
Controls whether to allow documented exceptions that are not declared if
they are a subclass of java.lang.RuntimeException.
|
void |
setExcludeScope(Scope excludeScope)
Set the excludeScope.
|
void |
setIgnoreMethodNamesRegex(java.util.regex.Pattern pattern)
Set regex for matching method names to ignore.
|
void |
setMinLineCount(int value)
Sets minimal amount of lines in method.
|
void |
setScope(Scope scope)
Set the scope.
|
void |
setValidateThrows(boolean value)
Allow validating throws tag.
|
private boolean |
shouldCheck(DetailAST ast,
Scope nodeScope)
Whether we should check this node.
|
beginTree, createClassInfo, findClassAlias, getCurrentClassName, getRequiredTokens, isSubclass, isUnchecked, leaveToken, logLoadErrorImpl, resolveClass, setLogLoadErrors, setSuppressLoadErrors, tryLoadClass, visitToken
destroy, finishTree, getClassLoader, getFileContents, getLine, getLines, getTabWidth, getTokenNames, init, log, log, setClassLoader, setFileContents, setMessages, setTabWidth, setTokens
getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, log, setId, setSeverity
configure, contextualize, finishLocalSetup, getConfiguration, setupChild
public static final java.lang.String MSG_JAVADOC_MISSING
public static final java.lang.String MSG_CLASS_INFO
public static final java.lang.String MSG_UNUSED_TAG_GENERAL
public static final java.lang.String MSG_INVALID_INHERIT_DOC
public static final java.lang.String MSG_UNUSED_TAG
public static final java.lang.String MSG_EXPECTED_TAG
public static final java.lang.String MSG_RETURN_EXPECTED
public static final java.lang.String MSG_DUPLICATE_TAG
private static final java.util.regex.Pattern MATCH_JAVADOC_ARG
private static final java.util.regex.Pattern MATCH_JAVADOC_ARG_MULTILINE_START
private static final java.util.regex.Pattern MATCH_JAVADOC_MULTILINE_CONT
private static final java.lang.String END_JAVADOC
private static final java.lang.String NEXT_TAG
private static final java.util.regex.Pattern MATCH_JAVADOC_NOARG
private static final java.util.regex.Pattern MATCH_JAVADOC_NOARG_MULTILINE_START
private static final java.util.regex.Pattern MATCH_JAVADOC_NOARG_CURLY
private static final int DEFAULT_MIN_LINE_COUNT
private Scope scope
private Scope excludeScope
private int minLineCount
private boolean allowUndeclaredRTE
private boolean validateThrows
private boolean allowThrowsTagsForSubclasses
private boolean allowMissingParamTags
private boolean allowMissingThrowsTags
private boolean allowMissingReturnTag
private boolean allowMissingJavadoc
private boolean allowMissingPropertyJavadoc
private java.util.List<java.lang.String> allowedAnnotations
private java.util.regex.Pattern ignoreMethodNamesRegex
public void setIgnoreMethodNamesRegex(java.util.regex.Pattern pattern)
pattern
- a pattern.public void setMinLineCount(int value)
value
- user's value.public void setValidateThrows(boolean value)
value
- user's value.public void setAllowedAnnotations(java.lang.String... userAnnotations)
userAnnotations
- user's value.public void setScope(Scope scope)
scope
- a scope.public void setExcludeScope(Scope excludeScope)
excludeScope
- a scope.public void setAllowUndeclaredRTE(boolean flag)
flag
- a Boolean
valuepublic void setAllowThrowsTagsForSubclasses(boolean flag)
flag
- a Boolean
valuepublic void setAllowMissingParamTags(boolean flag)
flag
- a Boolean
valuepublic void setAllowMissingThrowsTags(boolean flag)
flag
- a Boolean
valuepublic void setAllowMissingReturnTag(boolean flag)
flag
- a Boolean
valuepublic void setAllowMissingJavadoc(boolean flag)
flag
- a Boolean
valuepublic void setAllowMissingPropertyJavadoc(boolean flag)
flag
- a Boolean
valuepublic int[] getDefaultTokens()
AbstractCheck
getDefaultTokens
in class AbstractCheck
TokenTypes
public int[] getAcceptableTokens()
AbstractCheck
getAcceptableTokens
in class AbstractCheck
TokenTypes
public boolean isCommentNodesRequired()
AbstractCheck
isCommentNodesRequired
in class AbstractCheck
protected final void processAST(DetailAST ast)
AbstractTypeAwareCheck
processAST
in class AbstractTypeAwareCheck
ast
- the AST to process. Guaranteed to not be PACKAGE_DEF or
IMPORT tokens.private boolean hasAllowedAnnotations(DetailAST methodDef)
methodDef
- Some javadoc.private static int getMethodsNumberOfLine(DetailAST methodDef)
methodDef
- Some javadoc.protected final void logLoadError(AbstractTypeAwareCheck.Token ident)
AbstractTypeAwareCheck
logLoadError
in class AbstractTypeAwareCheck
ident
- class name for which we can no load class.protected boolean isMissingJavadocAllowed(DetailAST ast)
allowMissingJavadoc
and
allowMissingPropertyJavadoc
properties, do not forget
to call super.isMissingJavadocAllowed(ast)
in case
you want to keep this logic.ast
- the tree node for the method or constructor.private boolean isContentsAllowMissingJavadoc(DetailAST ast)
ast
- the tree node for the method or constructor.private boolean matchesSkipRegex(DetailAST methodDef)
methodDef
- METHOD_DEF
private boolean shouldCheck(DetailAST ast, Scope nodeScope)
ast
- a given node.nodeScope
- the scope of the node.private void checkComment(DetailAST ast, TextBlock comment)
ast
- the token for the methodcomment
- the Javadoc commentprivate boolean hasShortCircuitTag(DetailAST ast, java.util.List<JavadocTag> tags)
ast
- the construct being checkedtags
- the list of Javadoc tags associated with the constructprivate static Scope calculateScope(DetailAST ast)
ast
- the token of the method/constructorprivate static java.util.List<JavadocTag> getMethodTags(TextBlock comment)
comment
- the Javadoc commentprivate static int calculateTagColumn(java.util.regex.Matcher javadocTagMatcher, int lineNumber, int startColumnNumber)
javadocTagMatcher
- found javadoc tag matcherlineNumber
- line number of Javadoc tag in commentstartColumnNumber
- column number of Javadoc comment beginningprivate static java.util.List<JavadocTag> getMultilineArgTags(java.util.regex.Matcher argMultilineStart, int column, java.lang.String[] lines, int lineIndex, int tagLine)
argMultilineStart
- javadoc tag Matchercolumn
- column number of Javadoc taglines
- comment text lineslineIndex
- line number that contains the javadoc tagtagLine
- javadoc tag line number in fileprivate static java.util.List<JavadocTag> getMultilineNoArgTags(java.util.regex.Matcher noargMultilineStart, java.lang.String[] lines, int lineIndex, int tagLine)
noargMultilineStart
- javadoc tag Matcherlines
- comment text lineslineIndex
- line number that contains the javadoc tagtagLine
- javadoc tag line number in fileprivate static java.util.List<DetailAST> getParameters(DetailAST ast)
ast
- the method node.private java.util.List<JavadocMethodCheck.ExceptionInfo> getThrows(DetailAST ast)
ast
- the method node.private void checkParamTags(java.util.List<JavadocTag> tags, DetailAST parent, boolean reportExpectedTags)
tags
- the tags to checkparent
- the node which takes the parametersreportExpectedTags
- whether we should report if do not find
expected tagprivate static boolean searchMatchingTypeParameter(java.util.List<DetailAST> typeParams, java.lang.String requiredTypeName)
typeParams
- list of type parametersrequiredTypeName
- name of required typeprivate static boolean removeMatchingParam(java.util.List<DetailAST> params, java.lang.String paramName)
params
- collection of DetailAST parametersparamName
- name of parameterprivate void checkReturnTag(java.util.List<JavadocTag> tags, int lineNo, boolean reportExpectedTags)
tags
- the tags to checklineNo
- the line number of the expected tagreportExpectedTags
- whether we should report if do not find
expected tagprivate void checkThrowsTags(java.util.List<JavadocTag> tags, java.util.List<JavadocMethodCheck.ExceptionInfo> throwsList, boolean reportExpectedTags)
tags
- the tags to checkthrowsList
- the throws to checkreportExpectedTags
- whether we should report if do not find
expected tagprivate boolean isInThrows(java.util.List<JavadocMethodCheck.ExceptionInfo> throwsList, AbstractTypeAwareCheck.AbstractClassInfo documentedClassInfo, java.util.Set<java.lang.String> foundThrows)
throwsList
- list of throwsdocumentedClassInfo
- documented exception class infofoundThrows
- previously found throws