From df91057c1ead21b974824440a3363efb346e660f Mon Sep 17 00:00:00 2001 From: Oliver Burn Date: Mon, 21 Mar 2005 13:10:58 +0000 Subject: [PATCH] Fix up documentation. --- .../checks/javadoc/JavadocTypeCheck.java | 41 -- .../checks/javadoc/PackageHtmlCheck.java | 9 +- src/xdocs/config_javadoc.xml | 414 +++++++++--------- 3 files changed, 214 insertions(+), 250 deletions(-) diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheck.java index dcbfc7fea..c373b888d 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocTypeCheck.java @@ -33,48 +33,7 @@ import org.apache.regexp.RESyntaxException; import java.util.Vector; /** - *

* Checks the Javadoc of a type. - * By default, does not check for author or version tags. - * The scope to verify is specified using the {@link Scope} class and - * defaults to {@link Scope#PRIVATE}. To verify another scope, - * set property scope to one of the {@link Scope} constants. - * To define the format for an author tag or a version tag, - * set property authorFormat or versionFormat respectively to a - * - * regular expression. - *

- *

- * An example of how to configure the check is: - *

- * 
- * <module name="JavadocType"/>
- *
- *

An example of how to configure the check for the - * {@link Scope#PUBLIC} scope is: - *

- * 
- * <module name="JavadocType">
- *    <property name="scope" value="public"/>
- * </module>
- *
- *

An example of how to configure the check for an author tag - * and a version tag is: - *

- * 
- * <module name="JavadocType">
- *    <property name="authorFormat" value="\S"/>
- *    <property name="versionFormat" value="\S"/>
- * </module>
- *
- *

An example of how to configure the check for a - * CVS revision version tag is: - *

- * 
- * <module name="JavadocType">
- *    <property name="versionFormat" value="\$Revision.*\$"/>
- * </module>
- *
* * @author Oliver Burn * @author Michael Tamm diff --git a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java index 02044293a..2c937e432 100644 --- a/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java +++ b/src/checkstyle/com/puppycrawl/tools/checkstyle/checks/javadoc/PackageHtmlCheck.java @@ -27,15 +27,8 @@ import com.puppycrawl.tools.checkstyle.api.MessageDispatcher; import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck; /** - *

* Checks that all packages have a package documentation. - *

- *

- * An example of how to configure the check is: - *

- * 
- * <module name="PackageHtml"/>
- *
+ * * @author lkuehne */ public class PackageHtmlCheck extends AbstractFileSetCheck diff --git a/src/xdocs/config_javadoc.xml b/src/xdocs/config_javadoc.xml index 57071e03d..a7462c421 100755 --- a/src/xdocs/config_javadoc.xml +++ b/src/xdocs/config_javadoc.xml @@ -65,7 +65,17 @@

Checks Javadoc comments for class and interface definitions. + By default, does not check for author or version tags. The + scope to verify is specified using the Scope + class and defaults to Scope.PRIVATE. To verify + another scope, set property scope to one of the + Scope constants. To define the format for an + author tag or a version tag, set property authorFormat or + versionFormat respectively to a + + regular expression.

+ @@ -422,250 +432,252 @@ public int checkReturnTag(final int aTagIndex, TreeWalker

+ -
- -

- Checks that variables have Javadoc comments. -

- +
+ +

+ Checks that variables have Javadoc comments. +

+ - - - - - - - - - - - - - - - - - - - - -
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
excludeScopevisibility scope where Javadoc comments are not checkedscopenull
- + + + + + + + + + + + + + + + + + + + + +
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
excludeScopevisibility scope where Javadoc comments are not checkedscopenull
+ - -

- To configure the default check: -

- + +

+ To configure the default check: +

+ <module name="JavadocVariable"/> - + -

- To configure the check for public scope: -

- +

+ To configure the check for public + scope: +

+ + <module name="JavadocVariable"> <property name="scope" value="public"/> </module> - + -

- To configure the check for members which are in private, but not in protected scope: -

- +

+ To configure the check for members which are in private, but not in protected scope: +

+ + <module name="JavadocVariable"> <property name="scope" value="private"/> <property name="excludeScope" value="protected"/> </module> - - + + - -

- com.puppycrawl.tools.checkstyle.checks.javadoc -

- + +

+ com.puppycrawl.tools.checkstyle.checks.javadoc +

+ - -

- TreeWalker -

- -
+ +

+ TreeWalker +

+ +
-
- -

- Validates Javadoc comments to help ensure they are well - formed. The following checks are performed: -

+
+ +

+ 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). - Javadoc automatically places the first sentence in the - method summary table and index. With out proper - punctuation the Javadoc may be malformed. -
    • +
      +
    • + Ensures the first sentence ends with proper punctuation + (That is a period, question mark, or exclamation 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 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 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 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. +
    • +
-

- These checks were patterned after the checks made by the DocCheck - doclet available from Sun. -

- +

+ These checks were patterned after the checks made by the DocCheck + doclet available from Sun. +

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
excludeScopevisibility scope where Javadoc comments are not checkedscopenull
checkFirstSentence - Whether to check the first sentence for proper end of sentence. - booleantrue
checkEmptyJavadoc - Whether to check if the Javadoc is missing a describing text. - booleanfalse
checkHtmlWhether to check for incomplete html tags.booleantrue
tokensdefinitions to check
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - - -
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
excludeScopevisibility scope where Javadoc comments are not checkedscopenull
checkFirstSentence + Whether to check the first sentence for proper end of sentence. + booleantrue
checkEmptyJavadoc + Whether to check if the Javadoc is missing a describing text. + booleanfalse
checkHtmlWhether to check for incomplete html tags.booleantrue
tokensdefinitions to check - subset of tokens INTERFACE_DEF, - CLASS_DEF, - METHOD_DEF, - CTOR_DEF, - VARIABLE_DEF - + subset of tokens INTERFACE_DEF, + CLASS_DEF, + METHOD_DEF, + CTOR_DEF, + VARIABLE_DEF + - 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: -

+ +

+ To configure the default check: +

- + <module name="JavadocStyle"/> - + -

- To configure the check for public scope: -

+

+ To configure the check for public + scope: +

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

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

+

+ 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> - + -

- To configure the check to turn off first sentence checking: -

- +

+ To configure the check to turn off first sentence checking: +

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

- com.puppycrawl.tools.checkstyle.checks -

- + +

+ com.puppycrawl.tools.checkstyle.checks +

+ - -

- TreeWalker -

- -
+ +

+ TreeWalker +

+