From a168a3f583b277dcddf0606e00dbbe9ed6f3fe11 Mon Sep 17 00:00:00 2001 From: Oliver Burn Date: Wed, 19 Dec 2007 05:19:37 +0000 Subject: [PATCH] Add documentation for JavadocPackage check and "retire" the PackageHtml check. --- .../checks/javadoc/PackageHtmlCheck.java | 83 ------------------- .../checkstyle/configs/checkstyle_checks.xml | 2 +- .../checkstyle/ConfigurationLoaderTest.java | 2 +- .../checkstyle/checks/javadoc/AllTests.java | 2 +- .../checks/javadoc/PackageHtmlCheckTest.java | 32 ------- src/xdocs/config.xml | 10 +-- src/xdocs/config_javadoc.xml | 27 +++--- src/xdocs/configuration.xml | 8 +- src/xdocs/releasenotes.xml | 13 ++- 9 files changed, 37 insertions(+), 142 deletions(-) delete mode 100644 src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java delete mode 100644 src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheckTest.java diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java deleted file mode 100644 index 8f9ff3653..000000000 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java +++ /dev/null @@ -1,83 +0,0 @@ -//////////////////////////////////////////////////////////////////////////////// -// checkstyle: Checks Java source code for adherence to a set of rules. -// Copyright (C) 2001-2007 Oliver Burn -// -// This library is free software; you can redistribute it and/or -// modify it under the terms of the GNU Lesser General Public -// License as published by the Free Software Foundation; either -// version 2.1 of the License, or (at your option) any later version. -// -// This library is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// Lesser General Public License for more details. -// -// You should have received a copy of the GNU Lesser General Public -// License along with this library; if not, write to the Free Software -// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -//////////////////////////////////////////////////////////////////////////////// -package com.puppycrawl.tools.checkstyle.checks.javadoc; - -import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck; -import com.puppycrawl.tools.checkstyle.api.MessageDispatcher; -import java.io.File; -import java.util.HashSet; -import java.util.Set; - -/** - * Checks that all packages have a package documentation. - * - * @author lkuehne - */ -public class PackageHtmlCheck extends AbstractFileSetCheck -{ - /** - * Creates a new PackageHtmlCheck instance. - */ - public PackageHtmlCheck() - { - // java, not html! - // The rule is: Every JAVA file should have a package.html sibling - setFileExtensions(new String[]{"java"}); - } - - /** - * Checks that each java file in the fileset has a package.html sibling - * and fires errors for the missing files. - * @param aFiles a set of files - */ - public void process(File[] aFiles) - { - final File[] javaFiles = filter(aFiles); - final Set directories = getParentDirs(javaFiles); - for (File dir : directories) { - final File packageHtml = new File(dir, "package.html"); - final MessageDispatcher dispatcher = getMessageDispatcher(); - final String path = packageHtml.getPath(); - dispatcher.fireFileStarted(path); - if (!packageHtml.exists()) { - log(0, "javadoc.packageHtml"); - fireErrors(path); - } - dispatcher.fireFileFinished(path); - } - } - - /** - * Returns the set of directories for a set of files. - * @param aFiles s set of files - * @return the set of parent directories of the given files - */ - protected final Set getParentDirs(File[] aFiles) - { - final Set directories = new HashSet(); - for (File element : aFiles) { - final File f = element.getAbsoluteFile(); - if (f.getName().endsWith(".java")) { - final File dir = f.getParentFile(); - directories.add(dir); // duplicates are handled automatically - } - } - return directories; - } -} diff --git a/src/testinputs/com/puppycrawl/tools/checkstyle/configs/checkstyle_checks.xml b/src/testinputs/com/puppycrawl/tools/checkstyle/configs/checkstyle_checks.xml index 2630ee373..96737f513 100644 --- a/src/testinputs/com/puppycrawl/tools/checkstyle/configs/checkstyle_checks.xml +++ b/src/testinputs/com/puppycrawl/tools/checkstyle/configs/checkstyle_checks.xml @@ -25,6 +25,6 @@ - + \ No newline at end of file diff --git a/src/tests/com/puppycrawl/tools/checkstyle/ConfigurationLoaderTest.java b/src/tests/com/puppycrawl/tools/checkstyle/ConfigurationLoaderTest.java index 3dc23e4da..8c062109c 100644 --- a/src/tests/com/puppycrawl/tools/checkstyle/ConfigurationLoaderTest.java +++ b/src/tests/com/puppycrawl/tools/checkstyle/ConfigurationLoaderTest.java @@ -112,7 +112,7 @@ public class ConfigurationLoaderTest extends TestCase final Configuration[] children = config.getChildren(); atts.clear(); verifyConfigNode( - (DefaultConfiguration) children[1], "PackageHtml", 0, atts); + (DefaultConfiguration) children[1], "JavadocPackage", 0, atts); verifyConfigNode( (DefaultConfiguration) children[2], "Translation", 0, atts); atts.put("testName", "testValue"); diff --git a/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/AllTests.java b/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/AllTests.java index 9a40e9d70..dae444088 100644 --- a/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/AllTests.java +++ b/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/AllTests.java @@ -17,7 +17,7 @@ public class AllTests { suite.addTest(new TestSuite(JavadocStyleCheckTest.class)); suite.addTest(new TestSuite(JavadocTypeCheckTest.class)); suite.addTest(new TestSuite(JavadocVariableCheckTest.class)); - suite.addTest(new TestSuite(PackageHtmlCheckTest.class)); + suite.addTest(new TestSuite(JavadocPackageCheckTest.class)); suite.addTest(new TestSuite(WriteTagCheckTest.class)); return suite; diff --git a/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheckTest.java b/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheckTest.java deleted file mode 100644 index 9028cdf9d..000000000 --- a/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheckTest.java +++ /dev/null @@ -1,32 +0,0 @@ -package com.puppycrawl.tools.checkstyle.checks.javadoc; - -import com.puppycrawl.tools.checkstyle.BaseCheckTestCase; -import com.puppycrawl.tools.checkstyle.DefaultConfiguration; -import com.puppycrawl.tools.checkstyle.api.Configuration; - - -public class PackageHtmlCheckTest - extends BaseCheckTestCase -{ - protected DefaultConfiguration createCheckerConfig( - Configuration aCheckConfig) - { - final DefaultConfiguration dc = new DefaultConfiguration("root"); - dc.addChild(aCheckConfig); - return dc; - } - - public void testPackageHtml() - throws Exception - { - Configuration checkConfig = createCheckConfig(PackageHtmlCheck.class); - final String[] expected = { - "0: Missing package documentation file.", - }; - verify( - createChecker(checkConfig), - getPath("InputScopeAnonInner.java"), - getPath("package.html"), - expected); - } -} diff --git a/src/xdocs/config.xml b/src/xdocs/config.xml index 061f8d2f0..77f1bd07a 100755 --- a/src/xdocs/config.xml +++ b/src/xdocs/config.xml @@ -66,7 +66,7 @@ <module name="Checker"> - <module name="PackageHtml"/> + <module name="JavadocPackage"/> <module name="TreeWalker"> <module name="AvoidStarImport"/> <module name="ConstantName"/> @@ -82,10 +82,10 @@
  • Root module Checker has child - FileSetChecks PackageHtml and JavadocPackage and TreeWalker. (Module PackageHtml checks that all packages + class="code">JavadocPackage checks that all packages have package documentation.)
  • @@ -200,7 +200,7 @@ <module name="Checker"> - <module name="PackageHtml"/> + <module name="JavadocPackage"/> <module name="TreeWalker"> <property name="tabWidth" value="4"/> <module name="AvoidStarImport"/> @@ -325,7 +325,7 @@ <property name="basedir" value="src/checkstyle"/> <property name="localeCountry" value="DE"/> <property name="localeLanguage" value="de"/> - <module name="PackageHtml"/> + <module name="JavadocPackage"/> <module name="TreeWalker"> ... </module> diff --git a/src/xdocs/config_javadoc.xml b/src/xdocs/config_javadoc.xml index eaa51f501..0d6b21b01 100755 --- a/src/xdocs/config_javadoc.xml +++ b/src/xdocs/config_javadoc.xml @@ -8,12 +8,17 @@ -
    +

    - Checks that a package.html file - exists for each package. More specifically, checks that each - java file has a package.html sibling. + Checks that each Java package has a Javadoc comment. By default it + only allows a package-info.java file, but + can be configured to allow a package.html + file. +

    +

    + An error will be reported if both files exist as this is not + allowed by the Javadoc tool.

    @@ -26,15 +31,13 @@ default value - fileExtensions + allowLegacy - file type extension to identify java files. Setting this - property is typically only required if your java source - files are preprocessed and the original files do not have - the extension .java + If set then allow the use of a + package.html file. - String Set - java + boolean + false @@ -44,7 +47,7 @@ To configure the check:

    -<module name="PackageHtml"/> +<module name="JavadocPackage"/> diff --git a/src/xdocs/configuration.xml b/src/xdocs/configuration.xml index 5a83f1384..9b5d1b332 100755 --- a/src/xdocs/configuration.xml +++ b/src/xdocs/configuration.xml @@ -97,7 +97,7 @@ 
     <module name="Checker">
-    <module name="PackageHtml"/>
+    <module name="JavadocPackage"/>
     <module name="TreeWalker">
         <module name="AvoidStarImport"/>
         <module name="ConstantName"/>
@@ -113,10 +113,10 @@
       
      
         
    • 
           Root module Checker has child
-          FileSetChecks  PackageHtml and JavadocPackage and TreeWalker. (Module  PackageHtml checks that all packages
+          class="code">JavadocPackage checks that all packages
           have package documentation.)
         
      • 
         
    • 
@@ -230,7 +230,7 @@
 
       
       <module name="Checker">
-    <module name="PackageHtml"/>
+    <module name="JavadocPackage"/>
     <module name="TreeWalker">
         <property name="tabWidth" value="4"/>
         <module name="AvoidStarImport"/>
diff --git a/src/xdocs/releasenotes.xml b/src/xdocs/releasenotes.xml
index ae77f7e46..98d794c8e 100755
--- a/src/xdocs/releasenotes.xml
+++ b/src/xdocs/releasenotes.xml
@@ -20,9 +20,16 @@
       
      New Features:
      
       
        
         
      • 
-          New check GenericWhitespaceCheck for ensuring the whitespace
-          around the Generic tokens < and > are correct to the
-          typical convention.
+          New check GenericWhitespace
+          for ensuring the whitespace around the Generic tokens < and
+          > are correct to the typical convention.
+        
        • 
+        
      • 
+          New check JavadocPackage
+          for ensuring that each Java package has a Javadoc
+          comment. Replaces the check PackageHtml which has been removed.
         
        •