com.puppycrawl.tools.checkstyle.checks.javadoc

Class JavadocStyleCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.api.AutomaticBean

com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

com.puppycrawl.tools.checkstyle.api.AbstractCheck

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck

All Implemented Interfaces:

Configurable, Contextualizable

public class JavadocStyleCheck
extends AbstractCheck

Validates Javadoc comments to help ensure they are well formed.

The following checks are performed:

• Ensures the first sentence ends with proper punctuation (That is a period, question mark, or exclamation mark, by default). Javadoc automatically places the first sentence in the method summary table and index. Without proper punctuation the Javadoc may be malformed. All items eligible for the {@inheritDoc} tag are exempt from this requirement.
• Check text for Javadoc statements that do not have any description. This includes both completely empty Javadoc, and Javadoc with only tags such as @param and @return.
• Check text for incomplete HTML tags. Verifies that HTML tags have corresponding end tags and issues an "Unclosed HTML tag found:" error if not. An "Extra HTML tag found:" error is issued if an end tag is found without a previous open tag.
• Check that a package Javadoc comment is well-formed (as described above) and NOT missing from any package-info.java files.
• Check for allowed HTML tags. The list of allowed HTML tags is "a", "abbr", "acronym", "address", "area", "b", "bdo", "big", "blockquote", "br", "caption", "cite", "code", "colgroup", "dd", "del", "dfn", "div", "dl", "dt", "em", "fieldset", "font", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", "samp", "small", "span", "strong", "sub", "sup", "table", "tbody", "td", "tfoot", "th", "thead", "tr", "tt", "u", "ul", "var".

These checks were patterned after the checks made by the DocCheck doclet available from Sun. Note: Original Sun's DocCheck tool does not exist anymore.

• Property scope - Specify the visibility scope where Javadoc comments are checked. Type is com.puppycrawl.tools.checkstyle.api.Scope. Default value is private.
• Property excludeScope - Specify the visibility scope where Javadoc comments are not checked. Type is com.puppycrawl.tools.checkstyle.api.Scope. Default value is null.
• Property checkFirstSentence - Control whether to check the first sentence for proper end of sentence. Type is boolean. Default value is true.
• Property endOfSentenceFormat - Specify the format for matching the end of a sentence. Type is java.util.regex.Pattern. Default value is "([.?!][ \t\n\r\f<])|([.?!]$)".
• Property checkEmptyJavadoc - Control whether to check if the Javadoc is missing a describing text. Type is boolean. Default value is false.
• Property checkHtml - Control whether to check for incomplete HTML tags. Type is boolean. Default value is true.
• Property tokens - tokens to check Type is int[]. Default value is: ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, PACKAGE_DEF, VARIABLE_DEF.

To configure the default check:

 <module name="JavadocStyle"/>
 

Example:

 public class Test {
     /**
      * Some description here. // OK
      */
     private void methodWithValidCommentStyle() {}

     /**
      * Some description here // violation, the sentence must end with a proper punctuation
      */
     private void methodWithInvalidCommentStyle() {}
 }
 

To configure the check for public scope:

 <module name="JavadocStyle">
   <property name="scope" value="public"/>
 </module>
 

Example:

 public class Test {
     /**
      * Some description here // violation, the sentence must end with a proper punctuation
      */
     public void test1() {}

     /**
      * Some description here // OK
      */
     private void test2() {}
 }
 

To configure the check for javadoc which is in private, but not in package scope:

 <module name="JavadocStyle">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="package"/>
 </module>
 

Example:

 public class Test {
     /**
      * Some description here // violation, the sentence must end with a proper punctuation
      */
     private void test1() {}

     /**
      * Some description here // OK
      */
     void test2() {}
 }
 

To configure the check to turn off first sentence checking:

 <module name="JavadocStyle">
   <property name="checkFirstSentence" value="false"/>
 </module>
 

Example:

 public class Test {
     /**
      * Some description here // OK
      * Second line of description // violation, the sentence must end with a proper punctuation
      */
     private void test1() {}
 }
 

To configure the check to turn off validation of incomplete html tags:

 <module name="JavadocStyle">
 <property name="checkHtml" value="false"/>
 </module>
 

Example:

 public class Test {
     /**
      * Some description here // violation, the sentence must end with a proper punctuation
      * <p // OK
      */
     private void test1() {}
 }
 

To configure the check for only class definitions:

 <module name="JavadocStyle">
 <property name="tokens" value="CLASS_DEF"/>
 </module>
 

Example:

 /**
  * Some description here // violation, the sentence must end with a proper punctuation
  */
 public class Test {
     /**
      * Some description here // OK
      */
     private void test1() {}
 }
 

Parent is com.puppycrawl.tools.checkstyle.TreeWalker

Violation Message Keys:

• javadoc.empty
• javadoc.extraHtml
• javadoc.incompleteTag
• javadoc.missing
• javadoc.noPeriod
• javadoc.unclosedHtml

Since:

3.2

Nested Class Summary

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

AutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field and Description
static String	MSG_EMPTY Message property key for the Empty Javadoc message.
static String	MSG_EXTRA_HTML Message property key for the Extra HTML message.
static String	MSG_INCOMPLETE_TAG Message property key for the Incomplete Tag message.
static String	MSG_JAVADOC_MISSING Message property key for the Missing Javadoc message.
static String	MSG_NO_PERIOD Message property key for the No Javadoc end of Sentence Period message.
static String	MSG_UNCLOSED_HTML Message property key for the Unclosed HTML message.

Constructor Summary

Constructors

Constructor and Description
JavadocStyleCheck()

Method Summary

Modifier and Type	Method and Description
int[]	getAcceptableTokens() The configurable token set.
int[]	getDefaultTokens() Returns the default token a check is interested in.
int[]	getRequiredTokens() The tokens that this check must be registered for.
void	setCheckEmptyJavadoc(boolean flag) Setter to control whether to check if the Javadoc is missing a describing text.
void	setCheckFirstSentence(boolean flag) Setter to control whether to check the first sentence for proper end of sentence.
void	setCheckHtml(boolean flag) Setter to control whether to check for incomplete HTML tags.
void	setEndOfSentenceFormat(Pattern pattern) Setter to specify the format for matching the end of a sentence.
void	setExcludeScope(Scope excludeScope) Setter to specify the visibility scope where Javadoc comments are not checked.
void	setScope(Scope scope) Setter to specify the visibility scope where Javadoc comments are checked.
void	visitToken(DetailAST ast) Called to process a token.

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

beginTree, clearMessages, destroy, finishTree, getFileContents, getLine, getLines, getMessages, getTabWidth, getTokenNames, init, isCommentNodesRequired, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean

configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MSG_JAVADOC_MISSING

public static final String MSG_JAVADOC_MISSING

Message property key for the Missing Javadoc message.

See Also:

Constant Field Values

MSG_EMPTY

public static final String MSG_EMPTY

Message property key for the Empty Javadoc message.

See Also:

Constant Field Values

MSG_NO_PERIOD

public static final String MSG_NO_PERIOD

Message property key for the No Javadoc end of Sentence Period message.

See Also:

Constant Field Values

MSG_INCOMPLETE_TAG

public static final String MSG_INCOMPLETE_TAG

Message property key for the Incomplete Tag message.

See Also:

Constant Field Values

MSG_UNCLOSED_HTML

public static final String MSG_UNCLOSED_HTML

Message property key for the Unclosed HTML message.

See Also:

Constant Field Values

MSG_EXTRA_HTML

public static final String MSG_EXTRA_HTML

Message property key for the Extra HTML message.

See Also:

Constant Field Values

Constructor Detail

JavadocStyleCheck

public JavadocStyleCheck()

Method Detail

getDefaultTokens

public int[] getDefaultTokens()

Description copied from class: AbstractCheck

Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.

Specified by:

getDefaultTokens in class AbstractCheck

Returns:

the default tokens

See Also:

TokenTypes

getAcceptableTokens

public int[] getAcceptableTokens()

Description copied from class: AbstractCheck

The configurable token set. Used to protect Checks against malicious users who specify an unacceptable token set in the configuration file. The default implementation returns the check's default tokens.

Specified by:

getAcceptableTokens in class AbstractCheck

Returns:

the token set this check is designed for.

See Also:

TokenTypes

getRequiredTokens

public int[] getRequiredTokens()

Description copied from class: AbstractCheck

The tokens that this check must be registered for.

Specified by:

getRequiredTokens in class AbstractCheck

Returns:

the token set this must be registered for.

See Also:

TokenTypes

visitToken

public void visitToken(DetailAST ast)

Description copied from class: AbstractCheck

Called to process a token.

Overrides:

visitToken in class AbstractCheck

Parameters:

ast - the token to process

setScope

public void setScope(Scope scope)

Setter to specify the visibility scope where Javadoc comments are checked.

Parameters:

scope - a scope.

setExcludeScope

public void setExcludeScope(Scope excludeScope)

Setter to specify the visibility scope where Javadoc comments are not checked.

Parameters:

excludeScope - a scope.

setEndOfSentenceFormat

public void setEndOfSentenceFormat(Pattern pattern)

Setter to specify the format for matching the end of a sentence.

Parameters:

pattern - a pattern.

setCheckFirstSentence

public void setCheckFirstSentence(boolean flag)

Setter to control whether to check the first sentence for proper end of sentence.

Parameters:

flag - true if the first sentence is to be checked

setCheckHtml

public void setCheckHtml(boolean flag)

Setter to control whether to check for incomplete HTML tags.

Parameters:

flag - true if HTML checking is to be performed.

setCheckEmptyJavadoc

public void setCheckEmptyJavadoc(boolean flag)

Setter to control whether to check if the Javadoc is missing a describing text.

Parameters:

flag - true if empty Javadoc checking should be done.