From 730ade67d5f3f286c1004ce9a772fd4bc3bc9307 Mon Sep 17 00:00:00 2001 From: Rick Giles Date: Sat, 7 Dec 2002 12:02:32 +0000 Subject: [PATCH] changed to regular expressions for @author and @version tags - thanks to Lars for suggestion --- docs/checkstyle_checks.xml | 5 +- .../checkstyle/checks/JavadocTypeCheck.java | 98 ++++++++++++------- .../tools/checkstyle/InputJavadoc.java | 6 +- .../checkstyle/JavadocTypeCheckTest.java | 62 ++++++++++-- 4 files changed, 121 insertions(+), 50 deletions(-) diff --git a/docs/checkstyle_checks.xml b/docs/checkstyle_checks.xml index 623a889d0..1c123d143 100644 --- a/docs/checkstyle_checks.xml +++ b/docs/checkstyle_checks.xml @@ -1,5 +1,4 @@ - @@ -27,7 +26,9 @@ - + + + diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/JavadocTypeCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/JavadocTypeCheck.java index 60a01a1e3..6eec39130 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/JavadocTypeCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/JavadocTypeCheck.java @@ -29,33 +29,63 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes; import com.puppycrawl.tools.checkstyle.api.Utils; /** - * Checks that a type has Javadoc comment + *

+ * 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); }