From d92ceb81a67bb10b98f5ce305f839ba535a1c6ee Mon Sep 17 00:00:00 2001 From: Oliver Burn Date: Tue, 20 Aug 2002 13:08:37 +0000 Subject: [PATCH] Implemented enforcing having @version tag. (Request 543964). --- docs/anttask.html | 7 ++-- docs/cmdline.html | 4 +++ docs/engine.html | 2 +- docs/releasenotes.html | 1 + .../tools/checkstyle/CheckStyleTask.java | 6 ++++ .../tools/checkstyle/Configuration.java | 7 ++++ .../com/puppycrawl/tools/checkstyle/Defn.java | 2 ++ .../puppycrawl/tools/checkstyle/Verifier.java | 24 ++++++++++---- .../tools/checkstyle/messages.properties | 2 +- .../tools/checkstyle/CheckerTest.java | 32 +++++++++++++++++++ .../tools/checkstyle/InputJavadoc.java | 13 ++++++++ 11 files changed, 90 insertions(+), 10 deletions(-) create mode 100644 src/tests/com/puppycrawl/tools/checkstyle/InputJavadoc.java diff --git a/docs/anttask.html b/docs/anttask.html index b508e5385..3ea44f92b 100644 --- a/docs/anttask.html +++ b/docs/anttask.html @@ -227,6 +227,11 @@ This task is included in the checkstyle distribution.

Specifies whether to require that package documentation is available. Defaults to "false". No + + requireVersion + Specifies whether to require an @version tag to be defined for class and interface Javadoc comments. Defaults to "false". + No + ignoreImports Specifies whether to ignore checking import statements. Defaults to "false". @@ -414,8 +419,6 @@ This task is included in the checkstyle distribution.

files="checkstyle_report.html"/> </target> - -
diff --git a/docs/cmdline.html b/docs/cmdline.html index 30e1a292f..c04ea6dda 100644 --- a/docs/cmdline.html +++ b/docs/cmdline.html @@ -192,6 +192,10 @@ This command line tool is included in the checkstyle distribution.

checkstyle.require.packagehtml Specifies whether to require that package documentation is available. Defaults to "no". + + checkstyle.require.version + Specifies whether to require an @version tag to be defined for class and interface Javadoc comments. Defaults to "false". + checkstyle.ignore.imports Specifies whether to ignore checking import statements. Defaults to "no". diff --git a/docs/engine.html b/docs/engine.html index d199ae925..8dc07668c 100644 --- a/docs/engine.html +++ b/docs/engine.html @@ -64,7 +64,7 @@

You can require that a package.html file exists for each package. This check is turned off by default.

-

Javadoc comments for class and interface declarations are checked to ensure that the @author tag exists. This can be turned off.

+

Javadoc comments for class and interface declarations are checked to ensure that the @author and @version tags exist. These checks can be turned on/off.

You can control the visibility scope where Javadoc comments are checked. For example, you can check Javadoc code only for public and protected variables, methods, interfaces and class definitions. Scoping rules apply, in the above example a public method in a package visible class is not checked. You can also completely turn off all checking for Javadoc comments.

diff --git a/docs/releasenotes.html b/docs/releasenotes.html index d0be92b13..303340b80 100644 --- a/docs/releasenotes.html +++ b/docs/releasenotes.html @@ -46,6 +46,7 @@
  • Inspired by patch 580410 from Shinya Ohnuma, now the error message are localised.
  • Support checking to determine if an unused @throws exception is a subclass of java.lang.Error (request 583719).
  • Incorporate patch 590931 from Vijay Aravamudhan to improve documentation of the build.xml file.
    • +
  • Incorporate patch from Vijay Aravamudhan to enforce requiring @version tag (request 543964).

    • diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/CheckStyleTask.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/CheckStyleTask.java index a75a232a8..94092d51d 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/CheckStyleTask.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/CheckStyleTask.java @@ -200,6 +200,12 @@ public class CheckStyleTask setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, aAllowed); } + /** @param aRequired whether version tag **/ + public void setRequireVersion(final boolean aRequired) + { + setBooleanProperty(Defn.REQUIRE_VERSION_PROP, aRequired); + } + /** @param aLen max allowed line length **/ public void setMaxLineLen(final int aLen) { diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/Configuration.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/Configuration.java index c1af4e4e9..999da85e1 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/Configuration.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/Configuration.java @@ -209,6 +209,7 @@ public class Configuration setBooleanProperty(aProps, Defn.ALLOW_PROTECTED_PROP); setBooleanProperty(aProps, Defn.ALLOW_PACKAGE_PROP); setBooleanProperty(aProps, Defn.ALLOW_NO_AUTHOR_PROP); + setBooleanProperty(aProps, Defn.REQUIRE_VERSION_PROP); setJavadocScope( Scope.getInstance(aProps.getProperty(Defn.JAVADOC_CHECKSCOPE_PROP, Scope.PRIVATE.getName()))); @@ -508,6 +509,12 @@ public class Configuration return getBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP); } + /** @return whether to require having version tag */ + public boolean isRequireVersion() + { + return getBooleanProperty(Defn.REQUIRE_VERSION_PROP); + } + /** @return visibility scope where Javadoc is checked **/ public Scope getJavadocScope() { diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/Defn.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/Defn.java index b93204915..c1a451d5d 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/Defn.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/Defn.java @@ -75,6 +75,8 @@ public interface Defn "checkstyle.javadoc.checkUnusedThrows"; /** property name for requiring package documentation */ String REQUIRE_PACKAGE_HTML_PROP = "checkstyle.require.packagehtml"; + /** property name for requiring a version tag **/ + String REQUIRE_VERSION_PROP = "checkstyle.require.version"; /** property name for ignoring import statements **/ String IGNORE_IMPORTS_PROP = "checkstyle.ignore.imports"; /** property name for illegal import statements **/ diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/Verifier.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/Verifier.java index 6227ac2d5..d528e2db0 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/Verifier.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/Verifier.java @@ -93,6 +93,12 @@ class Verifier private static final RE MATCH_JAVADOC_AUTHOR = 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 + = createRE(MATCH_JAVADOC_VERSION_PAT); + //////////////////////////////////////////////////////////////////////////// // Member variables //////////////////////////////////////////////////////////////////////////// @@ -344,12 +350,18 @@ class Verifier if (jd == null) { mMessages.add(lineNo, "javadoc.missing", "type"); } - else if (!mConfig.isAllowNoAuthor() - && (mInScope.size() == 0) - // don't check author for inner classes - && (MATCH_JAVADOC_AUTHOR.grep(jd).length == 0)) - { - mMessages.add(lineNo, "type.missingAuthorTag"); + else if (mInScope.size() == 0) { + // don't check author/version for inner classes + if (!mConfig.isAllowNoAuthor() + && (MATCH_JAVADOC_AUTHOR.grep(jd).length == 0)) + { + mMessages.add(lineNo, "type.missingTag", "@author"); + } + if (mConfig.isRequireVersion() + && (MATCH_JAVADOC_VERSION.grep(jd).length == 0)) + { + mMessages.add(lineNo, "type.missingTag", "@version"); + } } } diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/messages.properties b/src/checkstyle/com/puppycrawl/tools/checkstyle/messages.properties index 092941d5f..a41409d7d 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/messages.properties +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/messages.properties @@ -31,7 +31,7 @@ javadoc.return.expected=Expected an @return tag. javadoc.classInfo=Unable to get class information for {0} tag ''{1}''. javadoc.packageHtml=missing package documentation file. -type.missingAuthorTag=type Javadoc comment is missing an @author tag. +type.missingTag=type Javadoc comment is missing an {0} tag. variable.missingJavadoc=variable ''{0}'' missing Javadoc. variable.notPrivate=variable ''{0}'' must be private and have accessor methods. diff --git a/src/tests/com/puppycrawl/tools/checkstyle/CheckerTest.java b/src/tests/com/puppycrawl/tools/checkstyle/CheckerTest.java index 2d8fffe5b..50d39faf8 100644 --- a/src/tests/com/puppycrawl/tools/checkstyle/CheckerTest.java +++ b/src/tests/com/puppycrawl/tools/checkstyle/CheckerTest.java @@ -49,6 +49,7 @@ public class CheckerTest mConfig.setLeftCurlyOptionProperty(Defn.LCURLY_TYPE_PROP, LeftCurlyOption.NL); mConfig.setRCurly(RightCurlyOption.ALONE); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, true); mConfig.setStringProperty(Defn.LOCALE_COUNTRY_PROP, Locale.ENGLISH.getCountry()); mConfig.setStringProperty(Defn.LOCALE_LANGUAGE_PROP, @@ -95,6 +96,7 @@ public class CheckerTest throws Exception { mConfig.setBooleanProperty(Defn.IGNORE_CAST_WHITESPACE_PROP, false); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, false); mConfig.setParenPadOption(PadOption.NOSPACE); mConfig.setBlockOptionProperty(Defn.TRY_BLOCK_PROP, BlockOption.IGNORE); mConfig.setBlockOptionProperty(Defn.CATCH_BLOCK_PROP, @@ -171,6 +173,7 @@ public class CheckerTest throws Exception { mConfig.setBooleanProperty(Defn.IGNORE_CAST_WHITESPACE_PROP, true); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, false); mConfig.setParenPadOption(PadOption.IGNORE); mConfig.setBlockOptionProperty(Defn.TRY_BLOCK_PROP, BlockOption.IGNORE); mConfig.setBlockOptionProperty(Defn.CATCH_BLOCK_PROP, @@ -241,6 +244,7 @@ public class CheckerTest throws Exception { mConfig.setBooleanProperty(Defn.IGNORE_WHITESPACE_PROP, true); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, false); mConfig.setBlockOptionProperty(Defn.TRY_BLOCK_PROP, BlockOption.IGNORE); mConfig.setBlockOptionProperty(Defn.CATCH_BLOCK_PROP, BlockOption.IGNORE); @@ -923,4 +927,32 @@ public class CheckerTest verify(c, filepath, expected); } + public void testNoAuthor() + throws Exception + { + mConfig.setWrapOpOption(WrapOpOption.NL); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, false); + final Checker c = createChecker(); + final String filepath = getPath("InputJavadoc.java"); + assertNotNull(c); + final String[] expected = { + filepath + ":11: type Javadoc comment is missing an @author tag." + }; + verify(c, filepath, expected); + } + + public void testNoVersion() + throws Exception + { + mConfig.setWrapOpOption(WrapOpOption.NL); + mConfig.setBooleanProperty(Defn.ALLOW_NO_AUTHOR_PROP, true); + mConfig.setBooleanProperty(Defn.REQUIRE_VERSION_PROP, true); + final Checker c = createChecker(); + final String filepath = getPath("InputJavadoc.java"); + assertNotNull(c); + final String[] expected = { + filepath + ":11: type Javadoc comment is missing an @version tag." + }; + verify(c, filepath, expected); + } } diff --git a/src/tests/com/puppycrawl/tools/checkstyle/InputJavadoc.java b/src/tests/com/puppycrawl/tools/checkstyle/InputJavadoc.java new file mode 100644 index 000000000..ee0d82847 --- /dev/null +++ b/src/tests/com/puppycrawl/tools/checkstyle/InputJavadoc.java @@ -0,0 +1,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. + */ +class InputJavadoc +{ +}