+ Validates Javadoc comments to help ensure they are well formed. + The following checks are performed: +
+ +These checks were patterned after the checks made by the DocCheck + doclet available from Sun.
+ +| name | +description | +type | +default value | +
|---|---|---|---|
| scope | +visibility scope where Javadoc comments are checked | +scope | +private | +
| checkFirstSentence | +Whether to check the first sentence for proper end of sentence. | +boolean | +true | +
| checkHtml | +Whether to check for incomplete html tags. | +boolean | +true | +
| tokens | +definitions to check | + +subset of tokens + INTERFACE_DEF, + CLASS_DEF, + METHOD_DEF, + CTOR_DEF, + VARIABLE_DEF + | ++ INTERFACE_DEF, + CLASS_DEF, + METHOD_DEF, + CTOR_DEF, + VARIABLE_DEF + | + +
+ To configure the default check: +
+ ++<module name="JavadocStyle"/> ++ +
+ To configure the check for public scope: +
+ ++<module name="JavadocStyle"> + <property name="scope" value="public"/> +</module> ++ +
+ To configure the check to turn off first sentence checking: +
++<module name="JavadocStyle"> + <property name="checkFirstSentence" value="false"/> +</module> ++ +
+ +
+ com.puppycrawl.tools.checkstyle.checks +
++ TreeWalker +
diff --git a/docs/releasenotes.html b/docs/releasenotes.html index bf909e1c3..684788209 100644 --- a/docs/releasenotes.html +++ b/docs/releasenotes.html @@ -58,6 +58,9 @@ 738205, 738388). Example listeners perform verbose and Commons Logging audits (request 737584). +int value
*/
public final void setTabWidth(int aTabWidth)
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Configuration.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Configuration.java
index 014178e2a..27cb46a9a 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Configuration.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Configuration.java
@@ -36,7 +36,7 @@ public interface Configuration extends Serializable
String[] getAttributeNames();
/**
- * The attribute value for an attribute name
+ * The attribute value for an attribute name.
* @param aName the attribute name
* @return the value that is associated with aName
* @throws CheckstyleException if aName is not a valid attribute name
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/DetailAST.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/DetailAST.java
index 3caf04461..1ac6bd2a7 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/DetailAST.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/DetailAST.java
@@ -77,7 +77,7 @@ public final class DetailAST
}
/**
- * Sets this AST's first Child
+ * Sets this AST's first Child.
* @param aAST the new first child
*/
public void setFirstChild(AST aAST)
@@ -90,7 +90,7 @@ public final class DetailAST
}
/**
- * Sets AST's next sibling
+ * Sets AST's next sibling.
* @param aAST the new next sibling
*/
public void setNextSibling(AST aAST)
@@ -102,7 +102,7 @@ public final class DetailAST
}
/**
- * Adds new child to AST
+ * Adds new child to AST.
* @param aAST the new child
*/
public void addChild(AST aAST)
@@ -151,7 +151,7 @@ public final class DetailAST
}
/**
- * Returns the parent token
+ * Returns the parent token.
* @return the parent token
*/
public DetailAST getParent()
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileSetCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileSetCheck.java
index 966d8467c..bb86ab67e 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileSetCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/FileSetCheck.java
@@ -51,6 +51,6 @@ public interface FileSetCheck
*/
void process(File[] aFiles);
- /** Cleans up the object **/
+ /** Cleans up the object. **/
void destroy();
}
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Filter.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Filter.java
index c68325ff4..af249d69f 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Filter.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Filter.java
@@ -26,7 +26,7 @@ package com.puppycrawl.tools.checkstyle.api;
public interface Filter
{
- /** The object is acceptable to this Filter */
+ /** The object is acceptable to this filter. */
int ACCEPT = -1;
/** The object is rejected by this filter. */
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/LocalizedMessages.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/LocalizedMessages.java
index 601c752e9..26604e634 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/LocalizedMessages.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/LocalizedMessages.java
@@ -41,14 +41,14 @@ public final class LocalizedMessages
mMessages.toArray(new LocalizedMessage[mMessages.size()]);
}
- /** Reset the object **/
+ /** Reset the object. **/
public void reset()
{
mMessages.clear();
}
/**
- * Logs a message to be reported
+ * Logs a message to be reported.
* @param aMsg the message to log
**/
public void add(LocalizedMessage aMsg)
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/MessageDispatcher.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/MessageDispatcher.java
index 41bc191ed..8f1514186 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/MessageDispatcher.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/MessageDispatcher.java
@@ -25,13 +25,13 @@ package com.puppycrawl.tools.checkstyle.api;
public interface MessageDispatcher
{
/**
- * Notify all listeners about the beginning of a file audit
+ * Notify all listeners about the beginning of a file audit.
* @param aFileName the file to be audited
*/
void fireFileStarted(String aFileName);
/**
- * Notify all listeners about the end of a file audit
+ * Notify all listeners about the end of a file audit.
* @param aFileName the audited file
*/
void fireFileFinished(String aFileName);
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Scope.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Scope.java
index 4efb9b57a..a1c70e64a 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Scope.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/Scope.java
@@ -59,27 +59,27 @@ public final class Scope implements Comparable, Serializable
/** anon inner scopename */
private static final String SCOPENAME_ANONINNER = "anoninner";
- /** nothing scope */
+ /** nothing scope. */
public static final Scope NOTHING =
new Scope(SCOPECODE_NOTHING, SCOPENAME_NOTHING);
- /** public scope */
+ /** public scope. */
public static final Scope PUBLIC =
new Scope(SCOPECODE_PUBLIC, SCOPENAME_PUBLIC);
- /** protected scope */
+ /** protected scope. */
public static final Scope PROTECTED =
new Scope(SCOPECODE_PROTECTED, SCOPENAME_PROTECTED);
- /** package scope */
+ /** package scope. */
public static final Scope PACKAGE =
new Scope(SCOPECODE_PACKAGE, SCOPENAME_PACKAGE);
- /** private scope */
+ /** private scope. */
public static final Scope PRIVATE =
new Scope(SCOPECODE_PRIVATE, SCOPENAME_PRIVATE);
- /** anon inner scope */
+ /** anon inner scope. */
public static final Scope ANONINNER =
new Scope(SCOPECODE_ANONINNER, SCOPENAME_ANONINNER);
@@ -121,8 +121,8 @@ public final class Scope implements Comparable, Serializable
*/
public int compareTo(Object aObject)
{
- Scope scope = (Scope) aObject;
- return this.mCode - scope.mCode;
+ final Scope s = (Scope) aObject;
+ return this.mCode - s.mCode;
}
/**
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/SeverityLevel.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/SeverityLevel.java
index a89d1ca2a..1687222ab 100755
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/SeverityLevel.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/SeverityLevel.java
@@ -59,7 +59,7 @@ public final class SeverityLevel implements Comparable, Serializable
public static final SeverityLevel INFO =
new SeverityLevel(SEVERITYCODE_INFO, SEVERITYNAME_INFO);
- /** Severity level: warning */
+ /** Severity level: warning. */
public static final SeverityLevel WARNING =
new SeverityLevel(SEVERITYCODE_WARNING, SEVERITYNAME_WARNING);
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/TokenTypes.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/TokenTypes.java
index 0f07945d7..0dd0657ee 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/api/TokenTypes.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/api/TokenTypes.java
@@ -518,7 +518,7 @@ public final class TokenTypes
* For example:
*
* implements Serializable, Comparable
- *
+ *
* parses as:
*
* +--IMPLEMENTS_CLAUSE
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/GenericIllegalRegexpCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/GenericIllegalRegexpCheck.java
index 05e736071..8454afd3c 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/GenericIllegalRegexpCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/GenericIllegalRegexpCheck.java
@@ -32,6 +32,7 @@ import com.puppycrawl.tools.checkstyle.api.DetailAST;
* bad pratice such as calling
* ex.printStacktrace(), System.out.println(), System.exit(), etc.
*
+ *
* An example of how to configure the check for calls to
* System.out.println is:
*
@@ -55,7 +56,7 @@ public class GenericIllegalRegexpCheck extends AbstractFormatCheck
private boolean mIgnoreCase = false;
/**
- * Setter for message property
+ * Setter for message property.
* @param aMessage custom message which should be used
* to report about violations.
*/
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/LineSeparatorOption.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/LineSeparatorOption.java
index b8d5bee19..bfddbccac 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/LineSeparatorOption.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/LineSeparatorOption.java
@@ -32,19 +32,19 @@ public final class LineSeparatorOption extends AbstractOption
/** maps from a string representation to an option */
private static final Map STR_TO_OPT = new HashMap();
- /** Windows-style line separators **/
+ /** Windows-style line separators. **/
public static final LineSeparatorOption CRLF =
new LineSeparatorOption("crlf", "\r\n");
- /** Mac-style line separators **/
+ /** Mac-style line separators. **/
public static final LineSeparatorOption CR =
new LineSeparatorOption("cr", "\r");
- /** Unix-style line separators **/
+ /** Unix-style line separators. **/
public static final LineSeparatorOption LF =
new LineSeparatorOption("lf", "\n");
- /** System default line separators **/
+ /** System default line separators. **/
public static final LineSeparatorOption SYSTEM = new LineSeparatorOption(
"system", System.getProperty("line.separator"));
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java
index 679bc346c..2bd9db8a6 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/RegexpHeaderCheck.java
@@ -52,7 +52,7 @@ import com.puppycrawl.tools.checkstyle.api.Utils;
* characters. Line 4 enforces that the copyright notice includes a four digit
* year. Line 5 is an example how to enforce revision control keywords in a file
* header.
- * An example of how to configure the check to use header file
+ * An example of how to configure the check to use header file
* "java.header" and ignore lines 4 and 5 is:
*
*
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedIfDepthCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedIfDepthCheck.java
index 06941dba9..506eb6c9f 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedIfDepthCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedIfDepthCheck.java
@@ -32,7 +32,7 @@ public final class NestedIfDepthCheck extends AbstractNestedDepthCheck
/** default allowed nesting depth. */
private static final int DEFAULT_MAX = 1;
- /** Creates new check instance with default allowed nesting depth */
+ /** Creates new check instance with default allowed nesting depth. */
public NestedIfDepthCheck()
{
super(DEFAULT_MAX);
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedTryDepthCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedTryDepthCheck.java
index 2721baca9..f9dd650e0 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedTryDepthCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/NestedTryDepthCheck.java
@@ -30,7 +30,7 @@ public final class NestedTryDepthCheck extends AbstractNestedDepthCheck
/** default allowed nesting depth */
private static final int DEFAULT_MAX = 1;
- /** Creates new check instance with default allowed nesting depth */
+ /** Creates new check instance with default allowed nesting depth. */
public NestedTryDepthCheck()
{
super(DEFAULT_MAX);
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/RedundantThrowsCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/RedundantThrowsCheck.java
index 9607f8834..3d491c3d7 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/RedundantThrowsCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/coding/RedundantThrowsCheck.java
@@ -58,7 +58,7 @@ public class RedundantThrowsCheck
private boolean mAllowSubclasses = false;
/**
- * Getter for allowUnchecked property
+ * Getter for allowUnchecked property.
* @param aAllowUnchecked whether unchecked excpetions in throws
* are allowed or not
*/
@@ -68,7 +68,7 @@ public class RedundantThrowsCheck
}
/**
- * Getter for allowSubclasses property
+ * Getter for allowSubclasses property.
* @param aAllowSubclasses whether subclass of another declared
* exception is allowed in throws clause
*/
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/design/VisibilityModifierCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/design/VisibilityModifierCheck.java
index 5a348a3be..11219cb0a 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/design/VisibilityModifierCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/design/VisibilityModifierCheck.java
@@ -63,7 +63,7 @@ public class VisibilityModifierCheck
/** regexp for public members that should be ignored */
private RE mPublicMemberRE = null;
- /** Constructor */
+ /** Create an instance. */
public VisibilityModifierCheck()
{
setPublicMemberPattern(mPublicMemberPattern);
@@ -91,7 +91,7 @@ public class VisibilityModifierCheck
}
/**
- * Set whether package visible members are allowed
+ * Set whether package visible members are allowed.
* @param aPackageAllowed whether package visible members are allowed
*/
public void setPackageAllowed(boolean aPackageAllowed)
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/imports/IllegalImportCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/imports/IllegalImportCheck.java
index a0c52220b..56f3a63f4 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/imports/IllegalImportCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/imports/IllegalImportCheck.java
@@ -32,6 +32,7 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes;
* are
* not 100% Pure Java.
*
+ *
* To reject other packages, set property illegalPkgs to a comma-separated
* list of the illegal packages.
*
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/indentation/BlockParentHandler.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/indentation/BlockParentHandler.java
index c61dc32d4..b41c25021 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/indentation/BlockParentHandler.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/indentation/BlockParentHandler.java
@@ -34,7 +34,7 @@ import com.puppycrawl.tools.checkstyle.api.TokenTypes;
* is called
* PersistenceOption
+ * Returns the set PersistenceOption.
* @return the set PersistenceOption
*/
public PersistenceOption getPersistenceOption()
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/LocalInterfaceMethodChecker.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/LocalInterfaceMethodChecker.java
index 9002f37a3..d728c68a4 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/LocalInterfaceMethodChecker.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/LocalInterfaceMethodChecker.java
@@ -30,8 +30,8 @@ public class LocalInterfaceMethodChecker
{
/**
- * Constructs a LocalInterfaceMethodChecker for a
- * local interface check.
+ * Constructs a LocalInterfaceMethodChecker for a local
+ * interface check.
* @param aCheck the local interface check.
*/
public LocalInterfaceMethodChecker(LocalInterfaceCheck aCheck)
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/RemoteInterfaceMethodChecker.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/RemoteInterfaceMethodChecker.java
index 8a5ac97e5..e45273ae7 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/RemoteInterfaceMethodChecker.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/j2ee/RemoteInterfaceMethodChecker.java
@@ -22,7 +22,7 @@ package com.puppycrawl.tools.checkstyle.checks.j2ee;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
/**
- * Checks methods of a remote interface
+ * Checks methods of a remote interface.
* @author Rick Giles
*/
public class RemoteInterfaceMethodChecker
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/HtmlTag.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/HtmlTag.java
new file mode 100755
index 000000000..617dc5347
--- /dev/null
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/HtmlTag.java
@@ -0,0 +1,108 @@
+////////////////////////////////////////////////////////////////////////////////
+// checkstyle: Checks Java source code for adherence to a set of rules.
+// Copyright (C) 2001-2003 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;
+
+/**
+ * Used to keep track of a tag and the text that follows it.
+ *
+ * @author Chris Stillwell
+ */
+class HtmlTag
+{
+ /** The maximum length of text to display with this tag. */
+ private static final int MAX_TEXT_LEN = 60;
+
+ /** The HTML tag name. */
+ private final String mId;
+
+ /** The line number in the source file where this tag was found. */
+ private final int mLineNo;
+
+ /** The position within the line where this tag was found. */
+ private final int mPosition;
+
+ /** The comment line of text where this tag appears. */
+ private final String mText;
+
+ /**
+ * Construct the HtmlTag.
+ * @param aId the HTML tag name.
+ * @param aLineNo the source line number of this tag.
+ * @param aPosition the position within the text of this tag.
+ * @param aText the line of comment text for this tag.
+ */
+ HtmlTag(String aId, int aLineNo, int aPosition, String aText)
+ {
+ mId = (aId.charAt(0) == '/') ? aId.substring(1) : aId;
+ mLineNo = aLineNo;
+ mPosition = aPosition;
+ mText = aText;
+ }
+
+ /**
+ * Returns the id (name) of this tag.
+ * @return a String id.
+ */
+ public String getId()
+ {
+ return mId;
+ }
+
+ /**
+ * Indicates if this tag is a close (end) tag.
+ * @return true is this is a close tag.
+ */
+ public boolean isCloseTag()
+ {
+ return (mText.charAt(mPosition + 1) == '/');
+ }
+
+ /**
+ * Returns the source line number where this tag was found.
+ * Used for displaying a Checkstyle error.
+ * @return an int line number.
+ */
+ public int getLineno()
+ {
+ return mLineNo;
+ }
+
+ /**
+ * Returns the position with in the comment line where this tag
+ * was found. Used for displaying a Checkstyle error.
+ * @return an int relative to zero.
+ */
+ public int getPosition()
+ {
+ return mPosition;
+ }
+
+ /**
+ * Returns this HTML tag and trailing text.
+ * Used for displaying a Checkstyle error.
+ * @return the String text of this tag.
+ */
+ public String toString()
+ {
+ final int startOfText = mPosition;
+ final int endOfText =
+ Math.min(startOfText + HtmlTag.MAX_TEXT_LEN, mText.length());
+ return mText.substring(startOfText, endOfText);
+ }
+}
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java
new file mode 100755
index 000000000..da14c9027
--- /dev/null
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java
@@ -0,0 +1,445 @@
+////////////////////////////////////////////////////////////////////////////////
+// checkstyle: Checks Java source code for adherence to a set of rules.
+// Copyright (C) 2001-2003 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.Check;
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.FileContents;
+import com.puppycrawl.tools.checkstyle.api.Scope;
+import com.puppycrawl.tools.checkstyle.api.ScopeUtils;
+import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+import java.util.Stack;
+import org.apache.regexp.RE;
+import org.apache.regexp.RESyntaxException;
+
+/**
+ * Custom Checkstyle Check to validate Javadoc.
+ * The following checks are performed:
+ *
+ * - Ensures the first sentence ends with proper punctuation (That is
+ * a period, question mark, or exclaimation mark). Javadoc automatically
+ * places the first sentence in the method summary table and index. With out
+ * proper punctuation the Javadoc may be malformed.
+ *
- Check text for incomplete html tags. Verifies that HTML tags have
+ * corresponding end tags and issues an UNCLOSED_HTML error if not.
+ * An EXTRA_HTML error is issued if an end tag is found without a previous
+ * open tag.
+ *
+ * These checks were patterned after the checks made by the doclet
+ * com.sun.tools.doclets.doccheck.DocCheck
+ *
+ * @author Chris Stillwell
+ * @version 1.1
+ */
+public class JavadocStyleCheck
+ extends Check
+{
+ /** Message property key for the Unclosed HTML message. */
+ private static final String UNCLOSED_HTML = "javadoc.unclosedhtml";
+
+ /** Message property key for the Extra HTML message. */
+ private static final String EXTRA_HTML = "javadoc.extrahtml";
+
+ /** HTML tags that do not require a close tag. */
+ private static final String[] SINGLE_TAG =
+ {"p", "br", "li", "dt", "dd", "td", "hr", "img", "tr", "th", "td"};
+
+ /** The scope to check. */
+ private Scope mScope = Scope.PRIVATE;
+
+ /** Regular expression for matching the end of a sentence. */
+ private RE mEndOfSentenceRE;
+
+ /**
+ * Indicates if the first sentence should be checked for proper end of
+ * sentence punctuation.
+ */
+ private boolean mCheckFirstSentence = true;
+
+ /**
+ * Indicates if the HTML within the comment should be checked.
+ */
+ private boolean mCheckHtml = true;
+
+ /**
+ * The default tokens this Check is used for.
+ * @see com.puppycrawl.tools.checkstyle.api.Check#getDefaultTokens()
+ */
+ public int[] getDefaultTokens()
+ {
+ return new int[] {
+ TokenTypes.INTERFACE_DEF,
+ TokenTypes.CLASS_DEF,
+ TokenTypes.METHOD_DEF,
+ TokenTypes.CTOR_DEF,
+ TokenTypes.VARIABLE_DEF,
+ };
+ }
+
+ /**
+ * Called to process a token.
+ * @see com.puppycrawl.tools.checkstyle.api.Check
+ */
+ public void visitToken(DetailAST aAST)
+ {
+ if (!ScopeUtils.inCodeBlock(aAST)) {
+ final DetailAST mods =
+ aAST.findFirstToken(TokenTypes.MODIFIERS);
+ final Scope declaredScope = ScopeUtils.getScopeFromMods(mods);
+ final Scope variableScope =
+ ScopeUtils.inInterfaceBlock(aAST)
+ ? Scope.PUBLIC
+ : declaredScope;
+
+ if (variableScope.isIn(mScope)) {
+ final Scope surroundingScope =
+ ScopeUtils.getSurroundingScope(aAST);
+
+ if ((surroundingScope == null)
+ || surroundingScope.isIn(mScope))
+ {
+ final FileContents contents = getFileContents();
+ final String[] cmt =
+ contents.getJavadocBefore(aAST.getLineNo());
+
+ checkComment(aAST, cmt);
+ }
+ }
+ }
+ }
+
+ /**
+ * Performs the various checks agains the Javadoc comment.
+ *
+ * @param aAST (Abstract Syntax Tree) the token to process.
+ * @param aComment the source lines that make up the Javadoc comment.
+ *
+ * @see #checkFirstSentence(DetailAST, String[])
+ */
+ private void checkComment(DetailAST aAST, String[] aComment)
+ {
+ if (aComment == null) {
+ return;
+ }
+
+ if (mCheckFirstSentence) {
+ checkFirstSentence(aAST, aComment);
+ }
+
+ if (mCheckHtml) {
+ checkHtml(aAST, aComment);
+ }
+ }
+
+ /**
+ * Checks that the first sentence ends with proper puctuation. This method
+ * uses a regular expression that checks for the presence of a period,
+ * question mark, or exclaimation mark followed either by whitespace, an
+ * HTML element, or the end of string.
+ *
+ * @param aAST (Abstract Syntax Tree) the token to process.
+ * @param aComment the source lines that make up the Javadoc comment.
+ */
+ private void checkFirstSentence(DetailAST aAST, String[] aComment)
+ {
+ final String commentText = getCommentText(aComment);
+
+ if ((commentText.length() != 0)
+ && !getEndOfSentenceRE().match(commentText))
+ {
+ log(aAST.getLineNo() - aComment.length, "javadoc.noperiod");
+ }
+ }
+
+ /**
+ * Returns the comment text from the Javadoc.
+ * @param aComments the lines of Javadoc.
+ * @return a comment text String.
+ */
+ private String getCommentText(String[] aComments)
+ {
+ final StringBuffer buffer = new StringBuffer();
+ boolean foundTag = false;
+
+ for (int i = 0; i < aComments.length; i++) {
+ String line = aComments[i];
+ final int textStart = findTextStart(line);
+
+ if (textStart != -1) {
+ // Look for Javadoc tag that's not a @link since can appear
+ // within the comment text.
+ final int ndx = line.indexOf('@');
+ if ((ndx != -1)
+ && !line.regionMatches(ndx + 1, "link", 0, "link".length()))
+ {
+ foundTag = true;
+ line = line.substring(0, ndx);
+ }
+
+ buffer.append(line.substring(textStart));
+ trimTail(buffer);
+ buffer.append('\n');
+
+ if (foundTag) {
+ break;
+ }
+ }
+ }
+
+ return buffer.toString().trim();
+ }
+
+ /**
+ * Finds the index of the first non-whitespace character ignoring the
+ * Javadoc comment start and end strings (/** and */) as well as any
+ * leading asterisk.
+ * @param aLine the Javadoc comment line of text to scan.
+ * @return the int index relative to 0 for the start of text
+ * or -1 if not found.
+ */
+ private int findTextStart(String aLine)
+ {
+ int textStart = -1;
+ for (int i = 0; i < aLine.length(); i++) {
+ if (!Character.isWhitespace(aLine.charAt(i))) {
+ if (aLine.regionMatches(i, "/**", 0, 3)) {
+ i += 2;
+ }
+ else if (aLine.regionMatches(i, "*/", 0, 2)) {
+ i++;
+ }
+ else if (aLine.charAt(i) != '*') {
+ textStart = i;
+ break;
+ }
+ }
+ }
+ return textStart;
+ }
+
+ /**
+ * Trims any trailing whitespace or the end of Javadoc comment string.
+ * @param aBuffer the StringBuffer to trim.
+ */
+ private void trimTail(StringBuffer aBuffer)
+ {
+ for (int i = aBuffer.length() - 1; i >= 0; i--) {
+ if (Character.isWhitespace(aBuffer.charAt(i))) {
+ aBuffer.deleteCharAt(i);
+ }
+ else if ((i > 0)
+ && (aBuffer.charAt(i - 1) == '*')
+ && (aBuffer.charAt(i) == '/'))
+ {
+ aBuffer.deleteCharAt(i);
+ aBuffer.deleteCharAt(i - 1);
+ i--;
+ }
+ else {
+ break;
+ }
+ }
+ }
+
+ /**
+ * 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
+ * primarily copied from the DocCheck checkHtml method.
+ *
+ * @param aAST (Abstract Syntax Tree) the token to process.
+ * @param aComment the source lines that make up the Javadoc comment.
+ */
+ private void checkHtml(DetailAST aAST, String[] aComment)
+ {
+ final int lineno = aAST.getLineNo() - aComment.length;
+ final Stack htmlStack = new Stack();
+
+ for (int i = 0; i < aComment.length; i++) {
+ final TagParser parser = new TagParser(aComment[i], lineno + i);
+ while (parser.hasNextTag()) {
+ final HtmlTag tag = parser.nextTag();
+
+ if (!tag.isCloseTag()) {
+ htmlStack.push(tag);
+ }
+ else {
+ // We have found a close tag.
+ if (isExtraHtml(tag.getId(), htmlStack)) {
+ // No corresponding open tag was found on the stack.
+ log(tag.getLineno(),
+ tag.getPosition(),
+ EXTRA_HTML,
+ tag);
+ }
+ else {
+ // See if there are any unclosed tags that were opened
+ // after this one.
+ checkUnclosedTags(htmlStack, tag.getId());
+ }
+ }
+ }
+ }
+
+ // Identify any tags left on the stack.
+ String lastFound = ""; // Skip multiples, like ...
+ for (int i = 0; i < htmlStack.size(); i++) {
+ final HtmlTag htag = (HtmlTag) htmlStack.elementAt(i);
+ if (!isSingleTag(htag) && !htag.getId().equals(lastFound)) {
+ log(htag.getLineno(), htag.getPosition(), UNCLOSED_HTML, htag);
+ lastFound = htag.getId();
+ }
+ }
+ }
+
+ /**
+ * Checks to see if there are any unclosed tags on the stack. The token
+ * represents a html tag that has been closed and has a corresponding open
+ * tag on the stack. Any tags, except single tags, that were opened
+ * (pushed on the stack) after the token are missing a close.
+ *
+ * @param aHtmlStack the stack of opened HTML tags.
+ * @param aToken the current HTML tag name that has been closed.
+ */
+ private void checkUnclosedTags(Stack aHtmlStack, String aToken)
+ {
+ final Stack unclosedTags = new Stack();
+ HtmlTag lastOpenTag = (HtmlTag) aHtmlStack.pop();
+ while (!aToken.equalsIgnoreCase(lastOpenTag.getId())) {
+ // Find unclosed elements. Put them on a stack so the
+ // output order won't be back-to-front.
+ if (isSingleTag(lastOpenTag)) {
+ lastOpenTag = (HtmlTag) aHtmlStack.pop();
+ }
+ else {
+ unclosedTags.push(lastOpenTag);
+ lastOpenTag = (HtmlTag) aHtmlStack.pop();
+ }
+ }
+
+ // Output the unterminated tags, if any
+ String lastFound = ""; // Skip multiples, like ..
+ for (int i = 0; i < unclosedTags.size(); i++) {
+ lastOpenTag = (HtmlTag) unclosedTags.get(i);
+ if (lastOpenTag.getId().equals(lastFound)) {
+ continue;
+ }
+ lastFound = lastOpenTag.getId();
+ log(lastOpenTag.getLineno(),
+ lastOpenTag.getPosition(),
+ UNCLOSED_HTML,
+ lastOpenTag);
+ }
+ }
+
+ /**
+ * Determines if the HtmlTag is one which does not require a close tag.
+ *
+ * @param aTag the HtmlTag to check.
+ * @return true if the HtmlTag is a single tag.
+ */
+ private boolean isSingleTag(HtmlTag aTag)
+ {
+ boolean isSingleTag = false;
+ for (int i = 0; i < SINGLE_TAG.length; i++) {
+ // If its a singleton tag (
,
, etc.), ignore it
+ // Can't simply not put them on the stack, since singletons
+ // like
and (unhappily) may either be terminated
+ // or not terminated. Both options are legal.
+ if (aTag.getId().equalsIgnoreCase(SINGLE_TAG[i])) {
+ isSingleTag = true;
+ }
+ }
+ return isSingleTag;
+ }
+
+ /**
+ * Determines if the given token is an extra HTML tag. This indicates that
+ * a close tag was found that does not have a corresponding open tag.
+ *
+ * @param aToken an HTML tag id for which a close was found.
+ * @param aHtmlStack a Stack of previous open HTML tags.
+ * @return false if a previous open tag was found
+ * for the token.
+ */
+ private boolean isExtraHtml(String aToken, Stack aHtmlStack)
+ {
+ boolean isExtra = true;
+ for (int i = 0; i < aHtmlStack.size(); i++) {
+ // Loop, looking for tags that are closed.
+ // The loop is needed in case there are unclosed
+ // tags on the stack. In that case, the stack would
+ // not be empty, but this tag would still be extra.
+ HtmlTag td = (HtmlTag) aHtmlStack.elementAt(i);
+ if (aToken.equalsIgnoreCase(td.getId())) {
+ isExtra = false;
+ break;
+ }
+ }
+
+ return isExtra;
+ }
+
+ /**
+ * Sets the scope to check.
+ * @param aFrom string to get the scope from
+ */
+ public void setScope(String aFrom)
+ {
+ mScope = Scope.getInstance(aFrom);
+ }
+
+ /**
+ * Returns a regular expression for matching the end of a sentence.
+ *
+ * @return a regular expression for matching the end of a sentence.
+ */
+ private RE getEndOfSentenceRE()
+ {
+ if (mEndOfSentenceRE == null) {
+ try {
+ mEndOfSentenceRE = new RE("([.?!][ \t\n\r\f<])|([.?!]$)");
+ }
+ catch (RESyntaxException e) {
+ // This should never occur.
+ e.printStackTrace();
+ }
+ }
+ return mEndOfSentenceRE;
+ }
+
+ /**
+ * Sets the flag that determines if the first sentence is checked for
+ * proper end of sentence punctuation.
+ * @param aFlag true if the first sentence is to be checked
+ */
+ public void setCheckFirstSentence(boolean aFlag)
+ {
+ mCheckFirstSentence = aFlag;
+ }
+
+ /**
+ * Sets the flag that determines if HTML checking is to be performed.
+ * @param aFlag true if HTML checking is to be performed.
+ */
+ public void setCheckHtml(boolean aFlag)
+ {
+ mCheckHtml = aFlag;
+ }
+
+}
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java
index f05174212..bdb453763 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java
@@ -26,6 +26,7 @@ import com.puppycrawl.tools.checkstyle.api.ScopeUtils;
import com.puppycrawl.tools.checkstyle.api.TokenTypes;
/**
+ *
* Checks that a variable has Javadoc comment.
* The scope to verify is specified using the {@link Scope} class and
* defaults to {@link Scope#PRIVATE}. To verify another scope,
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/TagParser.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/TagParser.java
new file mode 100755
index 000000000..9d1d0a36a
--- /dev/null
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/TagParser.java
@@ -0,0 +1,117 @@
+////////////////////////////////////////////////////////////////////////////////
+// checkstyle: Checks Java source code for adherence to a set of rules.
+// Copyright (C) 2001-2003 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 java.util.LinkedList;
+import java.util.List;
+import java.util.StringTokenizer;
+
+
+/**
+ * Helper class used to parse HTML tags from a single line of text.
+ * Just the beginning of the HTML tag is located. No attempt is made to
+ * parse out the complete tag, particularly since some of the tag
+ * parameters could be located on the following line of text. The
+ * hasNextTag and nextTag methods are used
+ * to iterate through the HTML tags that were found on the line of text.
+ *
+ * @author Chris Stillwell
+ */
+class TagParser
+{
+ /** List of HtmlTags found on the input line of text. */
+ private final List mTags = new LinkedList();
+
+ /**
+ * Constructs a TagParser and finds the first tag if any.
+ * @param aText the line of text to parse.
+ * @param aLineNo the source line number.
+ */
+ public TagParser(String aText, int aLineNo)
+ {
+ parseTags(aText, aLineNo);
+ }
+
+ /**
+ * Returns the next available HtmlTag.
+ * @return a HtmlTag or null if none available.
+ * @throws IndexOutOfBoundsException if there are no HtmlTags
+ * left to return.
+ */
+ public HtmlTag nextTag()
+ {
+ return (HtmlTag) mTags.remove(0);
+ }
+
+ /**
+ * Indicates if there are any more HtmlTag to retrieve.
+ * @return true if there are more tags.
+ */
+ public boolean hasNextTag()
+ {
+ return (mTags.size() > 0);
+ }
+
+ /**
+ * Performs lazy initialization on the internal tags List
+ * and adds the tag.
+ * @param aTag the HtmlTag to add.
+ */
+ private void add(HtmlTag aTag)
+ {
+ mTags.add(aTag);
+ }
+
+ /**
+ * Parses the text line for any HTML tags and adds them to the internal
+ * List of tags.
+ * @param aText the source line to parse.
+ * @param aLineNo the source line number.
+ */
+ private void parseTags(String aText, int aLineNo)
+ {
+ int position = 0;
+ final StringTokenizer tokenizer =
+ new StringTokenizer(aText, " \t\n\r\f<>", true);
+
+ while (tokenizer.hasMoreTokens()) {
+ String token = tokenizer.nextToken();
+ position += token.length();
+
+ if (token.equals("<")) {
+ token = tokenizer.nextToken();
+ position += token.length();
+
+ if (((token.charAt(0) >= 'A')
+ && (token.charAt(0) <= 'Z'))
+ || ((token.charAt(0) >= 'a')
+ && (token.charAt(0) <= 'z'))
+ || (token.charAt(0) == '/'))
+ {
+ // If a character or / follows the < sign,
+ // then assume its html.
+ // The non-html version is "<"
+ // Point before the angle bracket
+ final int startOfTag = position - token.length() - 1;
+ add(new HtmlTag(token, aLineNo, startOfTag, aText));
+ }
+ }
+ }
+ }
+}
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
index cb565e448..590520689 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
@@ -1,11 +1,14 @@
-javadoc.missing=Missing a Javadoc comment.
-javadoc.unusedTagGeneral=Unused Javadoc tag.
-javadoc.unusedTag=Unused {0} tag for ''{1}''.
+javadoc.classInfo=Unable to get class information for {0} tag ''{1}''.
javadoc.expectedTag=Expected {0} tag for ''{1}''.
+javadoc.extrahtml=Extra HTML tag found: {0}
+javadoc.missing=Missing a Javadoc comment.
+javadoc.noperiod=First sentence should end with a period.
+javadoc.packageHtml=Missing package documentation file.
javadoc.return.duplicate=Duplicate @return tag.
javadoc.return.expected=Expected an @return tag.
-javadoc.classInfo=Unable to get class information for {0} tag ''{1}''.
-javadoc.packageHtml=Missing package documentation file.
+javadoc.unclosedhtml=Unclosed HTML tag found: {0}
+javadoc.unusedTag=Unused {0} tag for ''{1}''.
+javadoc.unusedTagGeneral=Unused Javadoc tag.
type.missingTag=Type Javadoc comment is missing an {0} tag.
type.tagFormat=Type Javadoc tag {0} must match pattern ''{1}''.
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/metrics/CyclomaticComplexityCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/metrics/CyclomaticComplexityCheck.java
index f7a8eb3c6..9544c8eff 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/metrics/CyclomaticComplexityCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/metrics/CyclomaticComplexityCheck.java
@@ -39,7 +39,7 @@ public class CyclomaticComplexityCheck
/** default allowed complexity */
private static final int DEFAULT_VALUE = 10;
- /** Create an instance */
+ /** Create an instance. */
public CyclomaticComplexityCheck()
{
super(DEFAULT_VALUE);
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/naming/PackageNameCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/naming/PackageNameCheck.java
index fa638095c..205ef1c78 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/naming/PackageNameCheck.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/naming/PackageNameCheck.java
@@ -32,6 +32,7 @@ import com.puppycrawl.tools.checkstyle.checks.AbstractFormatCheck;
* and defaults to
* ^[a-z]+(\.[a-zA-Z_][a-zA-Z_0-9]*)*$.
*
+ *
*
+ *
* An example of how to configure the check is:
*
*
diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/whitespace/OperatorWrapOption.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/whitespace/OperatorWrapOption.java
index 56065b40c..fb43cb2c5 100644
--- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/whitespace/OperatorWrapOption.java
+++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/whitespace/OperatorWrapOption.java
@@ -34,9 +34,9 @@ public final class OperatorWrapOption
/** maps from a string representation to an option */
private static final Map STR_TO_OPT = new HashMap();
- /** require that the operator is on a new line **/
+ /** Require that the operator is on a new line. */
public static final OperatorWrapOption NL = new OperatorWrapOption("nl");
- /** require that the operator is at the end of the line **/
+ /** Require that the operator is at the end of the line. */
public static final OperatorWrapOption EOL = new OperatorWrapOption("eol");
/**
diff --git a/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadocStyleCheck.java b/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadocStyleCheck.java
new file mode 100755
index 000000000..5d4865eed
--- /dev/null
+++ b/src/testinputs/com/puppycrawl/tools/checkstyle/InputJavadocStyleCheck.java
@@ -0,0 +1,95 @@
+////////////////////////////////////////////////////////////////////////////////
+// Test case file for checkstyle.
+// Created: 2003
+////////////////////////////////////////////////////////////////////////////////
+
+package com.puppycrawl.tools.checkstyle;
+
+/**
+ * Test input for the JavadocStyleCheck. This check is used to perform
+ * some additional Javadoc validations.
+ *
+ * @author Chris Stillwell
+ * @version 1.0
+ */
+public class InputJavadocStyleCheck
+{
+ // This is OK. We don't flag missing javadoc. That's left for other checks.
+ private String first;
+
+ /** This Javadoc is missing an ending period */
+ private String second;
+
+ /**
+ * We don't want {@link com.puppycrawl.tools.checkstyle.checks.JavadocStyleCheck}
+ * tags to stop the scan for the end of sentence.
+ * @see Somthing
+ */
+ public InputJavadocStyleCheck()
+ {
+ }
+
+ /**
+ * This is ok!
+ */
+ private void method1()
+ {
+ }
+
+ /**
+ * This is ok?
+ */
+ private void method2()
+ {
+ }
+
+ /**
+ * And This is ok.
+ */
+ private void method3()
+ {
+ }
+
+ /**
+ * This should fail even.though.there are embedded periods
+ */
+ private void method4()
+ {
+ }
+
+ /**
+ * Test HTML in Javadoc comment
+ *
+ * - This guy is missing end of bold tag
+ *
- The dt and dd don't require end tags.
+ *
+ * Extra tag shouldn't be here
+ *
+ * @param arg1 dummy.
+ */
+ private void method5(int arg1)
+ {
+ }
+
+ /**
+ * Protected check should fail
+ */
+ protected void method6()
+ {
+ }
+
+ /**
+ * Package protected check should fail
+ */
+ void method7()
+ {
+ }
+
+ /**
+ * Public check should fail
+ */
+ public void method8()
+ {
+ }
+
+}
diff --git a/src/tests/com/puppycrawl/tools/checkstyle/AllTests.java b/src/tests/com/puppycrawl/tools/checkstyle/AllTests.java
index 921b13fde..682588637 100644
--- a/src/tests/com/puppycrawl/tools/checkstyle/AllTests.java
+++ b/src/tests/com/puppycrawl/tools/checkstyle/AllTests.java
@@ -60,6 +60,7 @@ import com.puppycrawl.tools.checkstyle.checks.j2ee.SessionBeanCheckTest;
import com.puppycrawl.tools.checkstyle.checks.j2ee.ThisParameterCheckTest;
import com.puppycrawl.tools.checkstyle.checks.j2ee.ThisReturnCheckTest;
import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMethodCheckTest;
+import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheckTest;
import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheckTest;
import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocVariableCheckTest;
import com.puppycrawl.tools.checkstyle.checks.javadoc.PackageHtmlCheckTest;
@@ -142,6 +143,7 @@ public class AllTests {
suite.addTest(new TestSuite(InnerAssignmentCheckTest.class));
suite.addTest(new TestSuite(InterfaceIsTypeCheckTest.class));
suite.addTest(new TestSuite(JavadocMethodCheckTest.class));
+ suite.addTest(new TestSuite(JavadocStyleCheckTest.class));
suite.addTest(new TestSuite(JavadocTypeCheckTest.class));
suite.addTest(new TestSuite(JavadocVariableCheckTest.class));
suite.addTest(new TestSuite(LineLengthCheckTest.class));
diff --git a/src/tests/com/puppycrawl/tools/checkstyle/SuppressionsLoaderTest.java b/src/tests/com/puppycrawl/tools/checkstyle/SuppressionsLoaderTest.java
index ab7571400..c408da6c4 100644
--- a/src/tests/com/puppycrawl/tools/checkstyle/SuppressionsLoaderTest.java
+++ b/src/tests/com/puppycrawl/tools/checkstyle/SuppressionsLoaderTest.java
@@ -49,14 +49,13 @@ public class SuppressionsLoaderTest extends TestCase
public void testNoFile()
throws CheckstyleException
{
- try
- {
- final FilterChain fc =
- SuppressionsLoader.loadSuppressions(
- "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_file.xml");
+ try {
+ SuppressionsLoader.loadSuppressions(
+ "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_file.xml");
}
catch (CheckstyleException ex) {
- assertEquals("unable to parse src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_file.xml - Attribute \"files\" is required and must be specified for element type \"suppress\".",
+ assertEquals(
+ "unable to parse src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_file.xml - Attribute \"files\" is required and must be specified for element type \"suppress\".",
ex.getMessage());
}
}
@@ -64,14 +63,13 @@ public class SuppressionsLoaderTest extends TestCase
public void testNoCheck()
throws CheckstyleException
{
- try
- {
- final FilterChain fc =
- SuppressionsLoader.loadSuppressions(
- "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_check.xml");
+ try {
+ SuppressionsLoader.loadSuppressions(
+ "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_check.xml");
}
catch (CheckstyleException ex) {
- assertEquals("unable to parse src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_check.xml - Attribute \"checks\" is required and must be specified for element type \"suppress\".",
+ assertEquals(
+ "unable to parse src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_no_check.xml - Attribute \"checks\" is required and must be specified for element type \"suppress\".",
ex.getMessage());
}
}
@@ -79,14 +77,13 @@ public class SuppressionsLoaderTest extends TestCase
public void testBadInt()
throws CheckstyleException
{
- try
- {
- final FilterChain fc =
- SuppressionsLoader.loadSuppressions(
- "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_bad_int.xml");
+ try {
+ SuppressionsLoader.loadSuppressions(
+ "src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_bad_int.xml");
}
catch (CheckstyleException ex) {
- assertEquals("number format exception src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_bad_int.xml - For input string: \"a\"",
+ assertEquals(
+ "number format exception src/testinputs/com/puppycrawl/tools/checkstyle/suppressions_bad_int.xml - For input string: \"a\"",
ex.getMessage());
}
}
diff --git a/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java b/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
new file mode 100755
index 000000000..a0a090342
--- /dev/null
+++ b/src/tests/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java
@@ -0,0 +1,125 @@
+package com.puppycrawl.tools.checkstyle.checks.javadoc;
+
+import com.puppycrawl.tools.checkstyle.BaseCheckTestCase;
+import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
+
+
+public class JavadocStyleCheckTest
+ extends BaseCheckTestCase
+{
+ public void testDefaultSettings()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocStyleCheck.class);
+ final String[] expected =
+ {
+ "20: First sentence should end with a period.",
+ "53: First sentence should end with a period.",
+ "63:11: Unclosed HTML tag found: This guy is missing end of bold tag",
+ "66:7: Extra HTML tag found: Extra tag shouldn't be here",
+ "68:19: Unclosed HTML tag found: dummy.",
+ "74: First sentence should end with a period.",
+ "75:23: Unclosed HTML tag found: should fail",
+ "81: First sentence should end with a period.",
+ "82:31: Unclosed HTML tag found: should fail",
+ "88: First sentence should end with a period.",
+ "89:31: Extra HTML tag found: "
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+ public void testFirstSentence() throws Exception
+ {
+ final DefaultConfiguration checkConfig = createCheckConfig(JavadocStyleCheck.class);
+ checkConfig.addAttribute("checkFirstSentence", "true");
+ checkConfig.addAttribute("checkHtml", "false");
+ final String[] expected =
+ {
+ "20: First sentence should end with a period.",
+ "53: First sentence should end with a period.",
+ "74: First sentence should end with a period.",
+ "81: First sentence should end with a period.",
+ "88: First sentence should end with a period.",
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+ public void testHtml() throws Exception
+ {
+ final DefaultConfiguration checkConfig = createCheckConfig(JavadocStyleCheck.class);
+ checkConfig.addAttribute("checkFirstSentence", "false");
+ checkConfig.addAttribute("checkHtml", "true");
+ final String[] expected =
+ {
+ "63:11: Unclosed HTML tag found: This guy is missing end of bold tag",
+ "66:7: Extra HTML tag found: Extra tag shouldn't be here",
+ "68:19: Unclosed HTML tag found: dummy.",
+ "75:23: Unclosed HTML tag found: should fail",
+ "82:31: Unclosed HTML tag found: should fail",
+ "89:31: Extra HTML tag found: "
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+ public void testScopePublic()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocStyleCheck.class);
+ checkConfig.addAttribute("checkFirstSentence", "true");
+ checkConfig.addAttribute("checkHtml", "true");
+ checkConfig.addAttribute("scope", "public");
+ final String[] expected =
+ {
+ "88: First sentence should end with a period.",
+ "89:31: Extra HTML tag found: "
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+ public void testScopeProtected()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocStyleCheck.class);
+ checkConfig.addAttribute("checkFirstSentence", "true");
+ checkConfig.addAttribute("checkHtml", "true");
+ checkConfig.addAttribute("scope", "protected");
+ final String[] expected =
+ {
+ "74: First sentence should end with a period.",
+ "75:23: Unclosed HTML tag found: should fail",
+ "88: First sentence should end with a period.",
+ "89:31: Extra HTML tag found: "
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+ public void testScopePackage()
+ throws Exception
+ {
+ final DefaultConfiguration checkConfig =
+ createCheckConfig(JavadocStyleCheck.class);
+ checkConfig.addAttribute("checkFirstSentence", "true");
+ checkConfig.addAttribute("checkHtml", "true");
+ checkConfig.addAttribute("scope", "package");
+ final String[] expected =
+ {
+ "74: First sentence should end with a period.",
+ "75:23: Unclosed HTML tag found: should fail",
+ "81: First sentence should end with a period.",
+ "82:31: Unclosed HTML tag found: should fail",
+ "88: First sentence should end with a period.",
+ "89:31: Extra HTML tag found: "
+ };
+
+ verify(checkConfig, getPath("InputJavadocStyleCheck.java"), expected);
+ }
+
+}