+ * Checks the Javadoc of a type. + * By default, does not check for author or version tags. + * The scope to verify is specified using the {@link Scope} class and + * defaults to {@link Scope#PRIVATE}. To verify another scope, + * set property scope to one of the {@link Scope} constants. + * To define the format for an author tag or a version tag + * set property authorFormat or versionFormat respectively to a + * regular expression + * (http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html). + *
+ *+ * An example of how to configure the check is: + *
+ *+ * <check name="JavadocTypeCheck"/> + *+ *
An example of how to configure the check for the + * {@link Scope#PUBLIC} scope is: + *
+ *+ * <check name="JavadocTypeCheck"> + * <property name="scope" value="public"/> + * </check> + *+ *
An example of how to configure the check for an author tag + * and a version tag is: + *
+ *+ * <check name="JavadocTypeCheck"> + * <property name="authorFormat" value="\S"/> + * <property name="versionFormat" value="\S"/> + * </check> + *+ *
An example of how to configure the check for a + * CVS revision version tag is: + *
+ *+ * <check name="JavadocTypeCheck"> + * <property name="versionFormat" value="\$Revision.*\$"/> + * </check> + ** + * @author Oliver Burn * @version 1.0 */ public class JavadocTypeCheck extends Check { - /** the pattern to match author tag **/ - private static final String MATCH_JAVADOC_AUTHOR_PAT = "@author\\s+\\S"; - /** compiled regexp to match author tag **/ - private static final RE MATCH_JAVADOC_AUTHOR = - Utils.createRE(MATCH_JAVADOC_AUTHOR_PAT); - - /** the pattern to match version tag **/ - private static final String MATCH_JAVADOC_VERSION_PAT = "@version\\s+\\S"; - /** compiled regexp to match version tag **/ - private static final RE MATCH_JAVADOC_VERSION = - Utils.createRE(MATCH_JAVADOC_VERSION_PAT); - /** the scope to check for */ private Scope mScope = Scope.PRIVATE; - /** whether to allow no author tag */ - private boolean mAllowNoAuthor = false; - /** whether to require version tag */ - private boolean mRequireVersion = false; - + /** compiled regexp to match author tag **/ + private RE mAuthorRE = null; + /** compiled regexp to match version tag **/ + private RE mVersionRE = null; + /** * Sets the scope to check. * @param aFrom string to set scope from @@ -65,25 +95,18 @@ public class JavadocTypeCheck mScope = Scope.getInstance(aFrom); } - /** - * Sets whether to allow no author tag - * @param aAllowNoAuthor a
boolean value
- */
- public void setAllowNoAuthor(boolean aAllowNoAuthor)
+ /** @param aFormat author tag pattern */
+ public void setAuthorFormat(String aFormat)
{
- mAllowNoAuthor = aAllowNoAuthor;
+ mAuthorRE = Utils.createRE("@author\\s+" + aFormat);
}
-
- /**
- * Sets whether to require a version tag.
- * @param aRequireVersion a boolean value
- */
- public void setRequireVersion(boolean aRequireVersion)
+
+ /** @param aFormat version tag pattern */
+ public void setVersionFormat(String aFormat)
{
- mRequireVersion = aRequireVersion;
+ mVersionRE = Utils.createRE("@version\\s+" + aFormat);
}
-
/** @see com.puppycrawl.tools.checkstyle.api.Check */
public int[] getDefaultTokens()
{
@@ -108,17 +131,20 @@ public class JavadocTypeCheck
}
else if (ScopeUtils.isOuterMostType(aAST)) {
// don't check author/version for inner classes
- if (!mAllowNoAuthor
- && (MATCH_JAVADOC_AUTHOR.grep(cmt).length == 0))
+ if ((mAuthorRE != null)
+ && (mAuthorRE.grep(cmt).length == 0))
{
+ // TODO: better error message
log(aAST.getLineNo(), "type.missingTag", "@author");
}
- if (mRequireVersion
- && (MATCH_JAVADOC_VERSION.grep(cmt).length == 0))
+ if ((mVersionRE != null)
+ && (mVersionRE.grep(cmt).length == 0))
{
+ // TODO: better error message
log(aAST.getLineNo(), "type.missingTag", "@version");
}
+
}
}
}
diff --git a/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadoc.java b/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadoc.java
index ee0d82847..aa91dda12 100644
--- a/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadoc.java
+++ b/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadoc.java
@@ -2,11 +2,13 @@
// Test case file for checkstyle.
// Created: 2001
////////////////////////////////////////////////////////////////////////////////
+
package com.puppycrawl.tools.checkstyle;
/**
- * Testing that the author and version tags are needed based on the
- * boolean property.
+ * Testing author and version tag patterns
+ * @author Oliver Burn
+ * @version 1.0
*/
class InputJavadoc
{
diff --git a/src/tests/com/puppycrawl/tools/checkstyle/JavadocTypeCheckTest.java b/src/tests/com/puppycrawl/tools/checkstyle/JavadocTypeCheckTest.java
index 2a7d7b039..036b2189c 100644
--- a/src/tests/com/puppycrawl/tools/checkstyle/JavadocTypeCheckTest.java
+++ b/src/tests/com/puppycrawl/tools/checkstyle/JavadocTypeCheckTest.java
@@ -136,10 +136,11 @@ public class JavadocTypeCheckTest extends BaseCheckTestCase
verify(c, fname, expected);
}
- public void testAts() throws Exception
+ public void testAuthorRequired() throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocTypeCheck.class);
+ checkConfig.addAttribute("authorFormat", "\\S");
final Checker c = createChecker(checkConfig);
final String fname = getPath("InputWhitespace.java");
final String[] expected =
@@ -148,35 +149,76 @@ public class JavadocTypeCheckTest extends BaseCheckTestCase
};
verify(c, fname, expected);
}
-
- public void testNoAuthor()
+
+ public void testAuthorRegularEx()
throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocTypeCheck.class);
- checkConfig.addAttribute("allowNoAuthor", "false");
- checkConfig.addAttribute("requireVersion", "false");
+ checkConfig.addAttribute("authorFormat", "0*");
final Checker c = createChecker(checkConfig);
final String fname = getPath("InputJavadoc.java");
final String[] expected = {
- "11: Type Javadoc comment is missing an @author tag."
};
verify(c, fname, expected);
}
- public void testNoVersion()
+ public void testAuthorRegularExError()
throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocTypeCheck.class);
- checkConfig.addAttribute("allowNoAuthor", "true");
- checkConfig.addAttribute("requireVersion", "true");
+ checkConfig.addAttribute("authorFormat", "ABC");
final Checker c = createChecker(checkConfig);
final String fname = getPath("InputJavadoc.java");
final String[] expected = {
- "11: Type Javadoc comment is missing an @version tag."
+ "13: Type Javadoc comment is missing an @author tag.",
+ };
+ verify(c, fname, expected);
+ }
+
+ public void testVersionRequired()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocTypeCheck.class);
+ checkConfig.addAttribute("versionFormat", "\\S");
+
+ final Checker c = createChecker(checkConfig);
+ final String fname = getPath("InputWhitespace.java");
+ final String[] expected = {
+ "13: Type Javadoc comment is missing an @version tag."
+ };
+ verify(c, fname, expected);
+ }
+
+ public void testVersionRegularEx()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocTypeCheck.class);
+ checkConfig.addAttribute("versionFormat", "[:digit:].*");
+
+ final Checker c = createChecker(checkConfig);
+ final String fname = getPath("InputJavadoc.java");
+ final String[] expected = {
+ };
+ verify(c, fname, expected);
+ }
+
+ public void testVersionRegularExError()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocTypeCheck.class);
+ checkConfig.addAttribute("versionFormat", "\\$Revision.*\\$");
+
+ final Checker c = createChecker(checkConfig);
+ final String fname = getPath("InputJavadoc.java");
+ final String[] expected = {
+ "13: Type Javadoc comment is missing an @version tag."
};
verify(c, fname, expected);
}