Add documentation for JavadocPackage check and "retire" the PackageHtml check.
This commit is contained in:
Oliver Burn
parent
ad727f351f
commit
a168a3f583
|
|
@ -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 <code>PackageHtmlCheck</code> 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<File> 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<File> getParentDirs(File[] aFiles)
|
||||
{
|
||||
final Set<File> directories = new HashSet<File>();
|
||||
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;
|
||||
}
|
||||
}
|
||||
|
|
@ -25,6 +25,6 @@
|
|||
<property name="format" value="System.out.println"/>
|
||||
</module>
|
||||
</module>
|
||||
<module name="PackageHtml"/>
|
||||
<module name="JavadocPackage"/>
|
||||
<module name="Translation"/>
|
||||
</module>
|
||||
|
|
@ -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");
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
}
|
||||
|
|
@ -66,7 +66,7 @@
|
|||
|
||||
<source>
|
||||
<module name="Checker">
|
||||
<module name="PackageHtml"/>
|
||||
<module name="JavadocPackage"/>
|
||||
<module name="TreeWalker">
|
||||
<module name="AvoidStarImport"/>
|
||||
<module name="ConstantName"/>
|
||||
|
|
@ -82,10 +82,10 @@
|
|||
<ul>
|
||||
<li>
|
||||
Root module <span class="code">Checker</span> has child
|
||||
FileSetChecks <span class="code"> PackageHtml</span> and <span
|
||||
FileSetChecks <span class="code">JavadocPackage</span> and <span
|
||||
class="code">TreeWalker</span>. (Module <a
|
||||
href="config_javadoc.html"> <span
|
||||
class="code">PackageHtml</span></a> checks that all packages
|
||||
class="code">JavadocPackage</span></a> checks that all packages
|
||||
have package documentation.)
|
||||
</li>
|
||||
<li>
|
||||
|
|
@ -200,7 +200,7 @@
|
|||
|
||||
<source>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -8,12 +8,17 @@
|
|||
</properties>
|
||||
|
||||
<body>
|
||||
<section name="PackageHtml">
|
||||
<section name="JavadocPackage">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Checks that a <span class="code">package.html</span> 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 <span class="code">package-info.java</span> file, but
|
||||
can be configured to allow a <span class="code">package.html</span>
|
||||
file.
|
||||
</p>
|
||||
<p>
|
||||
An error will be reported if both files exist as this is not
|
||||
allowed by the Javadoc tool.
|
||||
</p>
|
||||
</subsection>
|
||||
|
||||
|
|
@ -26,15 +31,13 @@
|
|||
<th>default value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>fileExtensions</td>
|
||||
<td>allowLegacy</td>
|
||||
<td>
|
||||
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 <span class="code">.java</span>
|
||||
If set then allow the use of a
|
||||
<span class="code">package.html</span> file.
|
||||
</td>
|
||||
<td><a href="property_types.html#stringSet">String Set</a></td>
|
||||
<td><span class="default">java</span></td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><span class="default">false</span></td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
|
|
@ -44,7 +47,7 @@
|
|||
To configure the check:
|
||||
</p>
|
||||
<source>
|
||||
<module name="PackageHtml"/>
|
||||
<module name="JavadocPackage"/>
|
||||
</source>
|
||||
</subsection>
|
||||
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@
|
|||
|
||||
<pre class="body">
|
||||
<module name="Checker">
|
||||
<module name="PackageHtml"/>
|
||||
<module name="JavadocPackage"/>
|
||||
<module name="TreeWalker">
|
||||
<module name="AvoidStarImport"/>
|
||||
<module name="ConstantName"/>
|
||||
|
|
@ -113,10 +113,10 @@
|
|||
<ul>
|
||||
<li>
|
||||
Root module <span class="code">Checker</span> has child
|
||||
FileSetChecks <span class="code"> PackageHtml</span> and <span
|
||||
FileSetChecks <span class="code">JavadocPackage</span> and <span
|
||||
class="code">TreeWalker</span>. (Module <a
|
||||
href="config_javadoc.html"> <span
|
||||
class="code">PackageHtml</span></a> checks that all packages
|
||||
class="code">JavadocPackage</span></a> checks that all packages
|
||||
have package documentation.)
|
||||
</li>
|
||||
<li>
|
||||
|
|
@ -230,7 +230,7 @@
|
|||
|
||||
<pre>
|
||||
<module name="Checker">
|
||||
<module name="PackageHtml"/>
|
||||
<module name="JavadocPackage"/>
|
||||
<module name="TreeWalker">
|
||||
<property name="tabWidth" value="4"/>
|
||||
<module name="AvoidStarImport"/>
|
||||
|
|
|
|||
|
|
@ -20,9 +20,16 @@
|
|||
<p>New Features:</p>
|
||||
<ul>
|
||||
<li>
|
||||
New check GenericWhitespaceCheck for ensuring the whitespace
|
||||
around the Generic tokens < and > are correct to the
|
||||
<i>typical</i> convention.
|
||||
New check <a
|
||||
href="config_whitespace.html#GenericWhitespace">GenericWhitespace</a>
|
||||
for ensuring the whitespace around the Generic tokens < and
|
||||
> are correct to the <i>typical</i> convention.
|
||||
</li>
|
||||
<li>
|
||||
New check <a
|
||||
href="config_javadoc.html#JavadocPackage">JavadocPackage</a>
|
||||
for ensuring that each Java package has a Javadoc
|
||||
comment. Replaces the check PackageHtml which has been removed.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue