diff --git a/docs/config_javadoc.html b/docs/config_javadoc.html index 9e1fca160..754d3561a 100644 --- a/docs/config_javadoc.html +++ b/docs/config_javadoc.html @@ -1,69 +1,172 @@ - - + + + Checks for Javadoc Comments - + - -

Checks for Javadoc Comments

+ + + + + + + +

Checks for Javadoc Comments

Checkstyle Logo
+ + + + + + + + +
+ + -

Checkstyle will check that the following constructs have a Javadoc comment:

-
    -
  • class
    • -
  • interface
    • -
  • variable
    • -
  • method
    • -
+

PackageHtml

Description

+

+ Checks that a package.html file exists for each + package. +

-

The property checkstyle.javadoc.scope controls -the visibility scope where Javadoc comments are checked. The property type is -scope and defaults to -private.

+

Example

+

+ To configure the check: +

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

For example, you can check Javadoc comments only for public and protected definitions -by setting the property to protected. Scoping -rules apply, so a public method in a package visible -class is not checked.

+

Package

+

+ com.puppycrawl.tools.checkstyle.checks +

+

Parent Module

+

+ Checker +

+

JavadocType

Description

+

+ Checks Javadoc comments for class and interface definitions. +

-

package.html check

+

Properties

-

The property checkstyle.require.packagehtml -controls whether to require that a package.html file -exists for each package. The property type is -boolean and defaults to -false.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
authorFormatpattern for @author tagregular expressionnull (tag not required)
versionFormatpattern for @version tagregular expressionnull (tag not required)
tokensdefinitions to checksubset of acceptable tokens INTERFACE_DEF, CLASS_DEFINTERFACE_DEF, CLASS_DEF
+

Examples

+

+ To configure the default check: +

+ 
+<module name="JavadocType"/>
+
+

+ To configure the check for public scope: +

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

+ To configure the check for an @author tag: +

+ 
+<module name="JavadocType">
+   <property name="authorFormat" value="\S"/>
+</module>
+
+

+ To configure the check for a CVS revision version tag: +

+ 
+<module name="JavadocType">
+   <property name="versionFormat" value="\$Revision.*\$"/>
+</module>
+
-

Class/Interface Javadoc checks

+

Package

+

+ com.puppycrawl.tools.checkstyle.checks +

+

Parent Module

+

+ TreeWalker +

-

The property checkstyle.require.version controls -whether to require an @version tag to be defined -for class and interface Javadoc comments. The property type is -boolean and defaults to -false.

+

JavadocMethod

Description

+

+ Checks to ensure that the following tags exist (if required): +

+
    +
  • + @return +
    • +
  • + @param +
    • +
  • + @throws or @exception +
    • +
  • + @see +
    • +
-

The property checkstyle.allow.noauthor controls -whether to allow no @author tag to be defined for -class and interface Javadoc comments. The property type is -boolean and defaults to -false.

- - -

Method Javadoc checks

- -

Javadoc comments for methods are checked to ensure that the following tags exist (if required):

-
    -
  • @return
    • -
  • @param
    • -
  • @throws or @exception
    • -
  • @see
    • -
- -

For example the following is valid:

-
+        

+        For example, the following is valid:
+        

+        
+        
     /**
      * Checks for a return tag.
      * @return the index of the next unchecked tag
@@ -74,42 +177,143 @@ class and interface Javadoc comments.  The property type is
     public int checkReturnTag(final int aTagIndex,
                               JavadocTag[] aTags,
                               int aLineNo)
-

+
-

The property checkstyle.javadoc.checkUnusedThrows -controls whether to check if an undocumented exception is a subclass of -java.lang.RuntimeException. The property type is -boolean and defaults to -false.

+

+ This supports the convention in the Sun + Javadoc Guidelines and the "Effective Java" book. +

-

This supports the convention in -the Sun Javadoc Guidelines -and the "Effective Java" book.

+

Properties

-

The classpath may need to be configured to locate the class -information. The classpath configuration is dependent on the mechanism used to -invoke Checkstyle.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
checkUnusedImportswhether to check if an undocumented exception is a subclass of + java.lang.RuntimeExceptionbooleanfalse
tokensdefinitions to checksubset of acceptable tokens METHOD_DEF, CTOR_DEFMETHOD_DEF, CTOR_DEF
-
-

Tip

+

Examples

+

+ To configure the default check: +

+ 
+<module name="JavadocMethod"/>
+
+

+ To configure the check for public scope and to + check for unused imports: +

+ 
+<module name="JavadocMethod">
+   <property name="scope" value="public"/>
+   <property name="checkUnusedThrows" value="true"/>
+</module>
+
+

Notes

-

It can be extremely painful writing or duplicating Javadoc for a method -required for an interface. Hence checkstyle supports using the convention of -using a single @see tag instead of all the other -tags. For example, if the previous method was implementing a method required -by the com.puppycrawl.tools.checkstyle.Verifier -interface, then the Javadoc could be done as:

- -
+        
    
+        
  • The classpath may need to be configured to locate the class information. The 
+        classpath configuration is dependent on the mechanism used to invoke Checkstyle.
+        
    • 
+        
  • 
+          It can be extremely painful writing or duplicating Javadoc for a method required 
+          for an interface. Hence checkstyle supports using the convention of using a 
+          single @see tag instead of all the other tags. For 
+          example, if the above method was implementing a method required by the 
+          com.puppycrawl.tools.checkstyle.Verifier interface, then the Javadoc 
+          could be done as:
+          
+          
         /** @see com.puppycrawl.tools.checkstyle.Verifier **/
     public int checkReturnTag(final int aTagIndex,
                               JavadocTag[] aTags,
                               int aLineNo)
-
    
-
+ + + +

Package

+

+ com.puppycrawl.tools.checkstyle.checks +

+

Parent Module

+

+ TreeWalker +

-
-

Copyright © 2002 Oliver Burn. All rights Reserved.

- +

JavadocVariable

Description

+

+ Checks that variables have Javadoc comments. +

+

Properties

+ + + + + + + + + + + + + + +
namedescriptiontypedefault value
scopevisibility scope where Javadoc comments are checkedscopeprivate
+ +

Examples

+

+ To configure the default check: +

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

+ To configure the check for public scope: +

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

Package

+

+ com.puppycrawl.tools.checkstyle.checks +

+

Parent Module

+

+ TreeWalker +

+
+
+

+ Copyright © 2002 Oliver Burn. All rights Reserved. +

+ +