TouchInstinct
/
checkstyle
306
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Implemented enforcing having @version tag. (Request 543964).

This commit is contained in:
Oliver Burn 2002-08-20 13:08:37 +00:00
parent b8d742ecd2
commit d92ceb81a6
11 changed files with 90 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/anttask.html
View File

@ -227,6 +227,11 @@ This task is included in the checkstyle distribution.</p>
<td valign="top">Specifies whether to require that package documentation is available. Defaults to <span class="default">&quot;false&quot;</span>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">requireVersion</td>
<td valign="top">Specifies whether to require an <span class="default">@version</span> tag to be defined for class and interface Javadoc comments. Defaults to <span class="default">&quot;false&quot;</span>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">ignoreImports</td>
<td valign="top">Specifies whether to ignore checking import statements. Defaults to <span class="default">&quot;false&quot;</span>.</td>
@ -414,8 +419,6 @@ This task is included in the checkstyle distribution.</p>
files=&quot;checkstyle_report.html&quot;/&gt;
&lt;/target&gt;
</pre>
<hr>

4
docs/cmdline.html
View File

@ -192,6 +192,10 @@ This command line tool is included in the checkstyle distribution.</p>
<td valign="top">checkstyle.require.packagehtml</td>
<td valign="top">Specifies whether to require that package documentation is available. Defaults to <span class="default">&quot;no&quot;</span>.</td>
</tr>
<tr>
<td valign="top">checkstyle.require.version</td>
<td valign="top">Specifies whether to require an <span class="default">@version</span> tag to be defined for class and interface Javadoc comments. Defaults to <span class="default">&quot;false&quot;</span>.</td>
</tr>
<tr>
<td valign="top">checkstyle.ignore.imports</td>
<td valign="top">Specifies whether to ignore checking import statements. Defaults to <span class="default">&quot;no&quot;</span>.</td>

2
docs/engine.html
View File

@ -64,7 +64,7 @@
<p>You can require that a <span class="code">package.html</span> file exists for each package. This check is turned off by default.</p>
<p>Javadoc comments for class and interface declarations are checked to ensure that the <span class="code">@author</span> tag exists. This can be turned off.</p>
<p>Javadoc comments for class and interface declarations are checked to ensure that the <span class="code">@author</span> and <span class="code">@version</span> tags exist. These checks can be turned on/off.</p>
<p>You can control the visibility scope where Javadoc comments are checked. For example, you can check Javadoc code only for <span class="code">public</span> and <span class="code">protected</span> 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.</p>

1
docs/releasenotes.html
View File

@ -46,6 +46,7 @@
<li class="body">Inspired by patch 580410 from Shinya Ohnuma, now the error message are localised.</li>
<li class="body">Support checking to determine if an unused <span class="code">@throws</span> exception is a subclass of <span class="code">java.lang.Error</span> (request 583719).</li>
<li class="body">Incorporate patch 590931 from Vijay Aravamudhan to improve documentation of the build.xml file.</li>
<li class="body">Incorporate patch from Vijay Aravamudhan to enforce requiring @version tag (request 543964).</li>
</ul>
</p>

6
src/checkstyle/com/puppycrawl/tools/checkstyle/CheckStyleTask.java
View File

@ -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)
{

7
src/checkstyle/com/puppycrawl/tools/checkstyle/Configuration.java
View File

@ -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()
{

2
src/checkstyle/com/puppycrawl/tools/checkstyle/Defn.java
View File

@ -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 **/

24
src/checkstyle/com/puppycrawl/tools/checkstyle/Verifier.java
View File

@ -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");
}
}
}

2
src/checkstyle/com/puppycrawl/tools/checkstyle/messages.properties
View File

@ -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.

32
src/tests/com/puppycrawl/tools/checkstyle/CheckerTest.java
View File

@ -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);
}
}

13
src/tests/com/puppycrawl/tools/checkstyle/InputJavadoc.java Normal file
View File

@ -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
{
}