Doc Check Doclet - Checking Documentation Comments

The Sun Doc Check doclet (DocCheck) is an API doc-comment checker for Java source files. DocCheck is a Javadoc doclet that identifies errors and generates templates for missing comments and comment-tags. It has multiple severity levels so you can focus on the most important errors first, and it provides both summary counts and a statistical breakdown of errors found. DocCheck process directories are recursively, so you don't need to specify a long list of packages. (You can also specify packages and classes to skip using the pattern-matching classes for filenames.)

Output
Running DocCheck
Doclet Options
Javadoc Options
Text-Control Options
Skip List Specifications
Troubleshooting
Notes

Output

DocCheck generates a series of Html files. Summaries are provided by package, by package group, and by class, with links to increasing levels of detail. In the detail pages, error message are shown on the left, and generated templates are shown on the right. On the right side, text that generated an errror is shown in red. Suggested-template text is shown in black.

Sample Output - For examples of the generated documents, see sampleOut/index.html.

For a list of errors that DocCheck finds, as well as those that it cannot find, and those it might possibly find in the future, see Errors Identified by DocCheck.

Running DocCheck

This section gives an overview of DocCheck's runtime options. These options are explained in detail below.

Sample Script - See the Sample script that produced the output given above.

You run DocCheck using the Javadoc -doclet and -docletpath switches:

javadoc -doclet com.sun.tools.doclets.doccheck.DocCheck \ -docletpath /home/user/doccheck1.2b2/doccheck.jar \ [packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2 ] [ options ]

Notes:

On Windows, the line continuation character is ^ (caret).

Instead of using -docletpath, you can put that path in your search path.

-subpackages is a standard Javadoc option. See the Javadoc tool reference page.

Doclet options:

-classlist -docletID

-authorID name -versionID string

-skipPkg p1:p2:... -skipClass c1:c2:...

-evident level -execDepth level

-d target -help

Javadoc options:

   -public -protected -sourcepath -docletpath

Additional options for control of generated text:

   -ifcTxt -getTxt -setTxt -isTxt -valTxt -cnrTxt -objTxt -bSetTxt -bValTxt

Sample command line:

javadoc -J-Xmx200m                                        \
        -doclet com.sun.tools.doclets.doccheck.DocCheck   \
        -docletpath /home/user/doccheck1.2b2/doccheck.jar \         
        -d jdkout2                                        \
        -classlist                                        \
        -docletID                                         \
        -title "Java 2 Platform, v1.3"                    \
        -skipPkg 'org.omg.CosNaming.*'                    \
        -execDepth 2                                      \
        -skipClass 'org.omg.*.*Helper:org.omg.*.*Holder'  \
        -sourcepath /home/user/src                        \
        com.package1  com.package2  MyClass.java

These commands are illustrated in the makeSample command script (written using the Unix CSH command shell). When run on the packages in sampleSrc directory, they produce the results shown in sampleOut.

Note: The options can be saved in a file and sent to javadoc with the @filename option. That reduces the command line to:
   javadoc @filename
Within the file, options can be on separate lines. (But an option that takes arguments must be on the same line with its arguments.) This option is most useful for specifying a long list of packages for Javadoc to process.

Doclet Options

-authorID name

Supplies the name used when an @author tag is generated. Default value is "unknown".
You might specify this on the command line, for example: -authorID "Your Name"
[Note: As with all DocCheck options, case is insignificant.]

-versionID string

Supplies the version string when an @version tag is generated. Default value is the standard version string used at Sun with the Source Code Control System (SCCS) utility: %I%, %G%, which becomes the current version and date, like this: "1.3 09/27/99".
You might specify this on the command line, for example: -versionID 1.04

-classlist

Generates a list of (outermost) classes that have errors and stores them in a file named classErr.lst. Fully-qualifed class names are generated, so that substituting slashes for the periods creates directory paths. The listing can then be used with a source control tool to check out the files and check them back in after making changes. [Unix authors using SCCS controled-files can use the checkin and checkout scripts.]

-d target

Specifies the output directory for generated files.

-docletID

Identifies the doclet version in the summary page. Useful for future automated merge tools and to keep track of which version generated the errors.

-skipPkg p1:p2:...

Specifies a list of package-patterns to skip, where each pattern represents a fully qualified package name and the package names are separated by the current system's path separator. Used when processing the Java platfrom to skip the org.omg.CosNaming packages and subpackages, which are automatically generated. The command line option that does that is:

-skipPkg org.omg.CosNaming.*

(See Skip List Specifications.)

-skipClass c1:c2:...

Specifies a list of classname-patterns to skip, where each pattern represents a fully qualified class name and the names are separated by the current system's path separator. Used when processing the Java platfrom to skip a series of Holder and Helper classes for which otherwise-redundant comments are specified in the package documentation. The command line option that does that is:

-skipClass 
    org.omg.*.*Helper:org.omg.*.*Holder

(See Skip List Specifications.)

-evident level

The error level to assign to methods missing comments which are "self-evident" by virtue of the method name, where "self-evident" is defined as "so obvious that this doclet can generate a comment for it". For example, the method getComponentName() would qualify as a (reasonably) self-evident method. It would have this comment generated for it: "Returns the component name". By default, such comments are treated the same as any other missing comment (error level 2: Missing comment). Using the -evident switch, you can reassign that error level to level 3 (tag error), 4 (text error), or 5 (warning).

-execDepth level

The package-depth for the executive summary. The default is 1, which provides an executive summary that goes one package deep. For the Java platform, that would summarize the results for java.*, javax.*, and org.*. In actual use, the Java platform is summarized at depth=2, which produces summaries for java.applet.*, java.awt.*, etc.

-help

Displays a help message to remind you of the possible options.

-eol

<Deprecated until standard doclet HtmlWriter class allows specifying EOL.>
Changes the line-termination character. The default is NL (LF), which is useful on most systems. (The system-specific line terminator is not used, in case the utility is being run over a network.) Options are:

Unix	The Unix line-terminator. See NL, below.
Dos	The DOS line-terminator. See CR+LF, below.
NL	The Unix line-terminator, "NewLine" (\n). Recognized by many DOS utilities, as well. This is the default value.
CR+LF	The DOS line-terminator, "CarriageReturn + LineFeed" (\r + \n).
LF	Same as NL. (On Unix systems, DOS LF is usually known as NL.)
CR	For completeness, in case some system uses it.
LF+CR	For completeness, in case some system uses it.

Note: Both the options and their values are case-insensitive.

Javadoc Options

These options are provided by Javadoc. There are other options, as well, described at http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/javadoc.html. But these are the main ones you'll need:

-public: Tells Javadoc to process only public classes and public members of classes.
-protected: Tells Javadoc to process both public and protected classes and members.
-sourcepath: Tells Javadoc where to find the specified packages and files. Very important if the -classpath option is used on the command line, since Javadoc uses the classpath if no sourcepath is specified! (That results in processing binary files.) When a package is specified, use the fully qualified package name. The sourcepath then points to the directory containing the first entry in the fully qualified name. When a file is specified, the sourcepath acts like a directory-path -- it names the directory that contains the file.
-classpath: Tells Javadoc where to find the classes needed for external references. in the JDK.
-docletpath: Tells Javadoc where to find the doclet. Names the directory containing the start of the fully qualified doclet name.

Text Control Options

For methods like getX(), setX(), and isX(), DocCheck generates a complete template with initial comment text and all tags fully specified. DocCheck includes a variety of options that let you control the text that is generated for the first line of an API comment. In each case, you follow the option with the word or phrase you want to use in that position. For example: -ifcTxt "This interface dictates that ...". The definitions below show some standard alternatives you can use, or you can make up your own.

-ifcTxt: The text to use for an interface. The default text is "Determines the requirements for an object that ..."
-getTxt: The text that precedes the property name in a method named getFoo(). The default phrase is "Returns the foo value". The -getTxt option replaces "Returns the".
Alternatives: "Retrieves the", "Gets the".
-setTxt: The text that precedes the property name in a method named setFoo() that sets a non-boolean variable. The default phrase is "Specifies the foo value". The -setTxt option replaces "Specifies the".
Alternative: "Sets the".
-isTxt: The text that precedes the property name in a method named isFoo(). The default phrase is "Returns true if this object is foo". The -isTxt option replaces "Returns true of this object is".
Alternative: "Determines if this object is".
-valTxt: The text that follows the property name in a method named getFoo() that returns a non-boolean variable. The default phrase is "Returns the foo value". The -valTxt option replaces "value".
Alternatives: "value for this object", "property" (useful for Java Bean components).
-cnrTxt: The initial text for a constructor. The default phrase is "Constructs {a/an} ObjectName object.". The -cnrTxt option replaces "Constructs". (Typically, you will want to modify this phrase to identify what is unique about this constructor relative to other constructors.)
Alternative: "Creates".
-objTxt: The final text for a constructor. The default phrase is "Constructs {a/an} ObjectName object". The -objTxt option replaces "object".
Alternative: "instance".
-bSetTxt: The text that precedes the property name in a method named setFoo() that sets a boolean variable. The default phrase is "Identifies this object as foo". The -bSetTxt option replaces "Identifies this object as".
Alternative: "Determines if this object is a".
-bValTxt: The text that follows the property name in a method named isFoo() and for a method named setFoo() that sets a boolean variable. The default value is the null string that follows "foo" in "Returns true if the value is foo" and "Identifies this object as foo".
Alternative: "value", when used with an alternative for -bSetTxt and -isTxt similar to those shown above for -getTxt and -setText

Skip List Specifications

A list of packages to skip can be specified with -skipPkg. A list of classes/interfaces to skip can be specified with -skipClass. For both options, "*" wildcards can be specified, as defined by the PathSpecifier class in pattern-matching classes for filenames.

Entries in the list are divided by the path separator for the current system (":" for Unix, ";" for DOS). Each entry in the list must be fully qualified, however, patterns can be specified. Patterns can be specified for each part of the path. So, "j*.s*" matches java.security as well as javax.swing. When the directory path ends with "*", all subdirecories are implied. So "-skipClass javax.swing.*.Foo" ignores all classes and interfaces named Foo in javax.swing and all sub-sub-(etc)-packages of javax.swing. To limit the specification to a single layer of packages, use "?*". Specifying javax.swing.?*.Foo would therefore skip classes and interfaces named Foo in subpackages of javax.swing, but not in sub-sub-packages. Here is the table of -skipPkg options for processing various combinations of packages from the swing hierarchy:

           swing
             |
         +---+---+
       table    text
                  |
                 html

javax.swing: The swing package only.
javax.swing.*: The swing package and all sub packages: table, text, and text.html.
javax.swing.*.*: All sub packages of swing, not including swing itself and all their subs, recursively: table, text, table.html.
javax.swing.?*: Direct descendants of swing, not including subpackages and not including swing itself: table, text. (This is the only time that "?" is recognized as a pattern-character. "?" has not yet been implemented as a general one-character template.)
javax.swing:javax.swing.?*: The swing package and any direct descendants.

Similar rules apply when specifying skip lists for classes.

Note that ignored classes, interfaces, and packages do not factor into the total number of packages, classes, and members processed. The statistics and percentages that are reported reflect only those items that are actually processed.

Troubleshooting

When you are having trouble using DocCheck, look here for insights.

No package, class, or source file named ...: Javadoc generates this error message when the -sourcepath option is invalid or missing. The named file always ends with a "dot", but that is simply a period. (When it occurs by itself, it looks like the OS shortcut for "current directory", but it is still just a period.) If the specified file(s) exist in the the current directory, or if the fully qualified package name starts in the current directory, you don't need to use the -sourcepath option. Otherwise, you need it. Check the Doclet Options section for more details on this option.
Strange output text...: If you point Javadoc at files that contain binary characters or files containing line-endings from a different system (for example DOS CR/LF-terminated files on a Unix system, you can get some truly weird output running across your screen. Don't do that.
No output...: Situation: You are positioned in the directory that contains a package. You run DocCheck, specifying the name of the package. The doclet seems to run, but no errors are generated -- and you *know* there are errors in the files.
Cause: The files in the package have a multi-part package name. (For example: package foo.bar;).
Solution: Javadoc requires a fully qualified package name. Position yourself to the directory that contains the start of the directory path and specify the fully-qualified name.

Notes

Some notes on DocCheck's features: how they work and how to use them:

Whenever possible, the DocCheck doclet creates comments and tags that can be cut and pasted into place in the source file. DocCheck generates as much English text as it reasonably can, to minimize the amount of typing you need to do.
Tags that have errors start with a "?". Tags that are intended for cut and paste operations start with "*".
To accomodate differences in phrasing, the tag-checker looks for a valid data type in the first 5 words of the text. That allows tags like
@param foo an int that...

and
```
@param foo the most recent int value...
```
To recognize data types encoded in HTML links, the comment parser breaks on < and > as well as spaces and array brackets. That, coupled with the 5-deep search for a data type, allows the parser to recognize
@param an <a href="...">URL</a>

as well as

@param an <a href="...">URL[]</a>
Within each error category, reports errors in "near file-order". (All fields, then all constructors, then all methods, and finally all inner classes. Each subgroup in file order.)
Errors broken down by severity level, so you can focus on the most important issues first.
Generates a comment-template when comments are missing.
Generates complete comment text and tags for setFoo(), getFoo(), and isFoo() methods.
Generates tag-templates when tags are missing, in a format suitable for cutting and pasting.
Generates additional verbage for int and boolean types. For example, generates the following for a boolean return value: * @return true if ...
Generates special text for arrays (ex: an array of Object)
Identifies missing, invalid, and extraneous @param, @return, and @exception tags (plus @author and @version for classes).
Allows specification of the text to use for generated @author and @verison tags.
Option for generating a file containing a list of (outermost) classes that have errors (classErr.lst).
Generates an intitial line of boilerplate for interfaces that are missing comments: "Defines the requirements for an object that ...".
Generates non-Javadoc comments for methods without comments that implement an interface. Comments are of the form //Inherited from java.awt.event.ActionListener. (In the standard doclet such methods inherit their comments from the interface.) The generated // comments can then be added to the source file to say, in effect, "This space intentionally left blank." (There is as yet no way for the doclet to check for the existence of such comments, so any class containing such methods is listed in the -classlist file, so the file can be inspected to see if the comments need to be added.)
You can control the text that DocCheck generates when the first line of text is missing from an API comment, so you can the kind of description you want.
Generates a line of text for overridden methods that identifies the source method and ignores missing tags for that method, since the standard doclet generates a link to the overridden method that the reader can follow for more information.
Generates a comment for methods that override other methods. The generated comment can simply be added to existing comments, or used as a reminder to fill in the reason for overriding the method.

`-classlist`	`-docletID`
`-authorID` name	`-versionID` string
`-skipPkg` p1:p2:...	`-skipClass` c1:c2:...
`-evident` level	`-execDepth` level
`-d` target	`-help`