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

Enhanced JavadocMethod to be more restrictive on where {@inheritDoc} can be used. Also enhanced JavadocPackage to ensure a package-info.java file contains a comment. Thanks to Travis Schneeberger for providing patch #2294029.

This commit is contained in:
Oliver Burn 2009-01-11 04:10:12 +00:00
parent 1c1eadb211
commit 9cff1673f1
10 changed files with 214 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheck.java
View File

@ -366,9 +366,11 @@ public class JavadocMethodCheck extends AbstractTypeAwareCheck
return false;
}
// Invalid if private or a constructor
// Invalid if private, a constructor, or a static method
if ((aAST.getType() == TokenTypes.CTOR_DEF)
|| (aScope == Scope.PRIVATE))
|| (aScope == Scope.PRIVATE)
|| (aAST.getType() == TokenTypes.METHOD_DEF
&& aAST.branchContains(TokenTypes.LITERAL_STATIC)))
{
log(aAST, "javadoc.invalidInheritDoc");
}

62
src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java
View File

@ -37,6 +37,7 @@ import java.util.regex.Pattern;
*
* @author Chris Stillwell
* @author Daniel Grenner
* @author Travis Schneeberger
* @version 1.2
*/
public class JavadocStyleCheck
@ -105,6 +106,7 @@ public class JavadocStyleCheck
TokenTypes.VARIABLE_DEF,
TokenTypes.ENUM_CONSTANT_DEF,
TokenTypes.ANNOTATION_FIELD_DEF,
TokenTypes.PACKAGE_DEF,
};
}
@ -127,6 +129,10 @@ public class JavadocStyleCheck
*/
private boolean shouldCheck(final DetailAST aAST)
{
if (aAST.getType() == TokenTypes.PACKAGE_DEF) {
return inPackageInfo();
}
if (ScopeUtils.inCodeBlock(aAST)) {
return false;
}
@ -165,11 +171,18 @@ public class JavadocStyleCheck
private void checkComment(final DetailAST aAST, final TextBlock aComment)
{
if (aComment == null) {
/*checking for missing docs in JavadocStyleCheck is not consistent
with the rest of CheckStyle... Even though, I didn't think it
made sense to make another check just to ensure that the
package-info.java file actually contains package Javadocs.*/
if (inPackageInfo()) {
log(aAST.getLineNo(), "javadoc.missing");
}
return;
}
if (mCheckFirstSentence) {
checkFirstSentence(aComment);
checkFirstSentence(aAST, aComment);
}
if (mCheckHtml) {
@ -182,26 +195,61 @@ public class JavadocStyleCheck
}
/**
* Checks that the first sentence ends with proper puctuation. This method
* Checks that the first sentence ends with proper punctuation. This method
* uses a regular expression that checks for the presence of a period,
* question mark, or exclaimation mark followed either by whitespace, an
* question mark, or exclamation mark followed either by whitespace, an
* HTML element, or the end of string. This method ignores {_AT_inheritDoc}
* comments.
* comments for TokenTypes that are valid for {_AT_inheritDoc}.
*
* @param aAST the current node
* @param aComment the source lines that make up the Javadoc comment.
*/
private void checkFirstSentence(TextBlock aComment)
private void checkFirstSentence(final DetailAST aAST, TextBlock aComment)
{
final String commentText = getCommentText(aComment.getText());
if ((commentText.length() != 0)
&& !getEndOfSentencePattern().matcher(commentText).find()
&& !"{@inheritDoc}".equals(commentText))
&& !("{@inheritDoc}".equals(commentText)
&& validForInheritDocOnly(aAST)))
{
log(aComment.getStartLineNo(), "javadoc.noperiod");
}
}
/**
* Checks to see if the current AST is valid to only contain an
* inheritDoc comment.
*
* @param aAST the current node
* @return true if inheritDoc comment valid
*/
private boolean validForInheritDocOnly(DetailAST aAST)
{
assert aAST != null;
final boolean validForMethod =
aAST.getType() == TokenTypes.METHOD_DEF
&& !aAST.branchContains(TokenTypes.LITERAL_STATIC)
&& ScopeUtils.getScopeFromMods(aAST.findFirstToken(
TokenTypes.MODIFIERS)) != Scope.PRIVATE;
return aAST.getType() == TokenTypes.ENUM_DEF
|| aAST.getType() == TokenTypes.CLASS_DEF
|| validForMethod
|| aAST.getType() == TokenTypes.INTERFACE_DEF;
}
/**
* Checks if the current file is a package-info.java file.
* @return true if the package file.
*/
private boolean inPackageInfo()
{
final FileContents contents = getFileContents();
return contents.getFilename().endsWith("package-info.java");
}
/**
* Checks that the Javadoc is not empty.
*
@ -299,7 +347,7 @@ public class JavadocStyleCheck
/**
* Checks the comment for HTML tags that do not have a corresponding close
* tag or a close tage that has no previous open tag. This code was
* tag or a close tag that has no previous open tag. This code was
* primarily copied from the DocCheck checkHtml method.
*
* @param aAST the node with the Javadoc

20
src/testinputs/com/puppycrawl/tools/checkstyle/javadoc/InputInheritDoc.java
View File

@ -24,4 +24,24 @@ public class InputInheritDoc
public void publicMethod()
{
}
/** {@inheritDoc} */
private static void privateStaticMethod()
{
}
/** {@inheritDoc} */
static void packageStaticMethod()
{
}
/** {@inheritDoc} */
protected static void protectedStaticMethod()
{
}
/** {@inheritDoc} */
public static void publicStaticMethod()
{
}
}

4
src/testinputs/com/puppycrawl/tools/checkstyle/javadoc/pkginfo/invalidformat/package-info.java Normal file
View File

@ -0,0 +1,4 @@
/**
* blah blah
*/
package com.puppycrawl.tools.checkstyle.javadoc.pkginfo.invalidformat;

4
src/testinputs/com/puppycrawl/tools/checkstyle/javadoc/pkginfo/invalidinherit/package-info.java Normal file
View File

@ -0,0 +1,4 @@
/**
* {@inheritDoc} Where are we inheriting from
*/
package com.puppycrawl.tools.checkstyle.javadoc.pkginfo.invalidinherit;

11
src/testinputs/com/puppycrawl/tools/checkstyle/javadoc/pkginfo/valid/package-info.java Normal file
View File

@ -0,0 +1,11 @@
/**
* This is a valid package documentation. <--- See the period after the
* first sentence.
*
* <p>
* hurray for javadocs in html
* <br>
* with a legacy non-closed br element
* </p>
*/
package com.puppycrawl.tools.checkstyle.javadoc.pkginfo.valid;

7
src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocMethodCheckTest.java
View File

@ -432,7 +432,12 @@ public class JavadocMethodCheckTest extends BaseCheckTestSupport
{
final String[] expected = {
"4:5: Invalid use of the {@inheritDoc} tag.",
"9:5: Invalid use of the {@inheritDoc} tag.",};
"9:5: Invalid use of the {@inheritDoc} tag.",
"29:5: Invalid use of the {@inheritDoc} tag.",
"34:5: Invalid use of the {@inheritDoc} tag.",
"39:5: Invalid use of the {@inheritDoc} tag.",
"44:5: Invalid use of the {@inheritDoc} tag.",
};
verify(mCheckConfig, getPath("javadoc/InputInheritDoc.java"), expected);
}
}

77
src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
View File

@ -1,8 +1,11 @@
package com.puppycrawl.tools.checkstyle.checks.javadoc;
import java.io.File;
import org.junit.Test;
import com.puppycrawl.tools.checkstyle.BaseCheckTestSupport;
import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
import org.junit.Test;
public class JavadocStyleCheckTest
@ -231,4 +234,76 @@ public class JavadocStyleCheckTest
verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
}
@Test
public void packageInfoInheritDoc() throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocStyleCheck.class);
final String[] expected =
{
"1: First sentence should end with a period.",
};
String basePath = "javadoc" + File.separator +
"pkginfo" + File.separator +
"invalidinherit" + File.separator;
verify(createChecker(checkConfig),
getPath(basePath + "package-info.java"),
expected);
}
@Test
public void packageInfoInvalid() throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocStyleCheck.class);
final String[] expected =
{
"1: First sentence should end with a period.",
};
String basePath = "javadoc" + File.separator +
"pkginfo" + File.separator +
"invalidformat" + File.separator;
verify(createChecker(checkConfig),
getPath(basePath + "package-info.java"),
expected);
}
@Test
public void packageInfoMissing() throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocStyleCheck.class);
final String[] expected =
{
"1: Missing a Javadoc comment."
};
String basePath = "javadoc" + File.separator +
"bothfiles" + File.separator;
verify(createChecker(checkConfig),
getPath(basePath + "package-info.java"),
expected);
}
@Test
public void packageInfoValid() throws Exception
{
final DefaultConfiguration checkConfig =
createCheckConfig(JavadocStyleCheck.class);
final String[] expected = {};
String basePath = "javadoc" + File.separator +
"pkginfo" + File.separator +
"valid" + File.separator;
verify(createChecker(checkConfig),
getPath(basePath + "package-info.java"),
expected);
}
}

29
src/xdocs/config_javadoc.xml
View File

@ -11,9 +11,10 @@
<section name="JavadocPackage">
<subsection name="Description">
<p>
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>
Checks that each Java package has a Javadoc file used for
commenting. 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>
@ -236,7 +237,18 @@
interface (this was <i>corrected</i> under Java 6). Hence
Checkstyle supports using the convention of using a single
<span class="code">{@inheritDoc}</span> tag instead of all the
other tags. For example, if the following method is
other tags.
</p>
<p>
Note that only inheritable items will allow the
<span class="code">{@inheritDoc}</span> tag to be used in place
of comments. Static methods at all visibilities, private non-static
methods and constructors are not inheritable.
</p>
<p>
For example, if the following method is
implementing a method required by an interface, then the
Javadoc could be done as:
</p>
@ -539,7 +551,9 @@ public boolean isSomething()
(That is a period, question mark, or exclamation mark, by default).
Javadoc automatically places the first sentence in the
method summary table and index. With out proper punctuation
the Javadoc may be malformed.
the Javadoc may be malformed. All items eligible for the
<span class="code">{@inheritDoc}</span> tag are exempt from this
requirement.
</li>
<li>
@ -555,6 +569,11 @@ public boolean isSomething()
error is issued if an end tag is found without a previous
open tag.
</li>
<li>
Check that a package Javadoc comment is well-formed (as
described above) and NOT missing from any package-info.java
files.
</li>
<li>
Check for allowed HTML tags. The list of allowed HTML tags
is "a", "abbr", "acronym", "address", "area", "b", "bdo",

10
src/xdocs/releasenotes.xml
View File

@ -78,6 +78,16 @@
check for allowed HTML tags. Thanks to Nicolas Dordet for
providing patch #2214251.
</li>
<li>
Enhanced <a
href="config_javadoc.html#JavadocMethod">JavadocMethod</a> to
be more restrictive on where <code>{@inheritDoc}</code> can be
used. Also enhanced <a
href="config_javadoc.html#JavadocPackage">JavadocPackage</a>
to ensure a <code>package-info.java</code> file contains a
comment. Thanks to Travis Schneeberger for providing patch
#2294029.
</li>
</ul>
<p>Fixed Bugs:</p>