Errors Identified by the Sun Doc Check Utility

This document details the errors that the Sun Doc Check Utility (DocCheck) finds, those that it cannot find at the present time, and those that it might find at some point in the future.

Error Categories (Severity Levels)
Errors DocCheck Can't Find
Errors Generated By DocCheck
Future Error Checks
Note:
For details on DocCheck's command line options and information on how to run DocCheck, see Checking API Specification-Comments with DocCheck.

Error Categories (Severity Levels )

The errors are arranged into multiple severity levels, so the most important errors can be fixed first.

Severity 1 Package, interface, (outer) class, or exception missing comments.

Severity 2 Inner class, inner interface, field, constructor, or method missing a comment. (When the required comment is so obvious that it can be automatically generated from the name of the method, as for example, getComponentColor(), the severity level can be reduced using the -evident switch.)

Severity 3
Tag errors caused by missing, incomplete, or extraneous tags. Produces tag templates suitable for cutting and pasting. For example:

* @param foo an int specifying the ... value

Severity 4
Text errors and link errors. Text errors are caused by unterminated HTML tags or a missing period in the first sentence of a comment, or by unterminated HTML tags anywhere in the body of the comment. Link errors are caused by missing @see links.

Note: The body of the comment is only checked if the first sentence was ok. The reason: if the first sentence contains something like "This method does: <ul> <li>one thing." Then this "first sentence" will contain unterminated html (ul and li). To check the "body" would now produce spurious errors. But to check the whole comment would duplicate real errors in the first sentence (for example, an unclosed bold tag). So DocCheck punts. Moral: Run DocCheck multiple times, until no errors occur. Then you know your API comments are clean.

Warning Generated for methods without comments that override a superclass method or implement an interface. Such methods need no comments, because it will be inherited. A warning is generated though, so the developer can check to see that a normal comment of the form // Inherited {<from>} is included in the code. Can also be the level assigned to "self-evident" comments using the -evident switch. May be used in the future.

Errors DocCheck Can't Find

This table lists errors that DocCheck is currently unable to report, either because they are intercepted by JavaDoc before the DocCheck doclet has a chance to see them, or because some other API extension is required to make them visible. When the JavaDoc API is extended so the doclet can access the errors, the contents of this list will move down to the Errors Generated by DocCheck section. The error level shown in the left column is the one that is anticipated for that error.

Level	Message	Meaning
Member (2)	Default Constructor	Default constructor is used. (A default constructors is not identified as such, so it is not possible for DocCheck to distinguish between a zero-arg constructor that has no arguments and a default constructor. When it becomes possible to distinguish them, a -default switch should be added to set the error level to use when they are missing a comment. Default=2)
Tag (3)	Missing Class	Generated for `@see fooMethod`, when `@see #fooMethod` was intended. (Missing # when referencing a member -- needed.)
	Can't find X	Generated for `@see #OtherClass`, when `@see OtherClass` was intended. (# present when referencing a class -- shouldn't be)
	Invalid Tag	Generated for `@parm foo`, when `@param foo` was intended. (misspelled tag name), or `@returns foo`, when `@return foo` is correct.
	No version text	An @version tag is present on a class, but has no text after it.
Warning (5)	No comment, implements or overrides	This warning is generated to suggest the addition of a `//`-comment (see below). The warning is generated even if such a comment already exists, because non-JavaDoc comments are not exposed to the doclet. Extraneous warnings can be eliminated when it becomes possible to access the (non-JavaDoc) comment immediately preceding an otherwise undocumented member.

Errors Generated by DocCheck

These are the errors that DocCheck currently generates. The left column shows the error level assigned to that error, as described in the Error Categories table above . Severity levels 1 & 2 are classified as major errors. Severity levels 3 and below are classified as minor errors.

	Level	Message	Meaning
M A J O R	Type (1)	No Comment	Missing comment on a package, outer class, or outer interface.
	Type (1)	No Text	Tags but no text on a package, outer class, or outer interface.
	Member (2)	No Comment	Missing comment on an inner class, inner interface, field, constructor, or method. (Unless they are methods that implement an interface or override a superclass, in which case they may generate a warning. See below.)
		No Text	Tags but no text on an inner class, inner interface, field, constructor, or method.
		No Comment or Text, but reasonably self-evident	A method is missing a comment or text, but the text can be generated in one of three ways: Parsing Method Name: A name like "getComponentName()" can be parsed into "Returns the component name". Single @see tag: If the comment contains a single @see tag, it can be assumed that the method delegates its behavior to some other method which contains the commentary. The text "Delegates to <target of @see tag>" can be generated for such methods. Single @return tag: If the method contains a single @return tag, the text can be generated from that tag, so `@return the component name` becomes "Returns the component name". [Note: The error level for these can be reassigned with the `-evident` switch.]
M I N O R	Tag (3)	Missing since	No @since tag on a package.
		Multiple version	Multiple @version tags on a package or class
		Param Tag Errors	Missing or invalid @param tags, tags without text, or extraneous @param tags (those for which the name matches none of the method's parameters). (However, if no param tags or return tags exist on a method that implements an interface or overrides a superclass, that is not considered an error.
		Return Tag Errors	Missing or invalid @return tags, tags without text, or extraneous @return tags (more than one).
		Exception Tag Errors	Missing or invalid @exception tags, or tags without text. (An invalid tag is one for which the class is not a subtype of Throwable.)
	Text (4)	Missing See Tag	Generated when `getFoo()` does not have an @see to `setFoo()`, or vice versa, and when `addFooListener()` does not have an @see to `removeFooListener()`, or vice versa. [Note: @see tag errors are considered "text" level errors]
		Bad See Tag	No text for the see tag. [Note: @see tag errors are considered "text" level errors]
		No period.	There is no period to end the first sentence of the comment. (The first sentence is the summary that goes on the index page. The lack of a period sometimes indicates a run-on construction that results in a paragraph or a page going into the index, where a sentence was intended.)
		HTML list in first sentence	Since a list occupies a lot of vertical space, it is frequently undesirable in the first sentence of a comment, because the first sentence appears in the index page, which is intended to contain a short summary line.
		Unterminated HTML	Generated by any HTML construct which requires a terminator which is not present. For example: <b>, <ul>, or <i>.
	Warning (5)	No comment, implements or overrides	Generated for a method without a comment when it overrides a superclass method or implements an interface. The warning is generated to ensure that the code contains a comment like `//Inherited {from >source>}`.

Future Error Checks

This section is a catch-all for listing errors that DocCheck might someday be able to catch, if it becomes clever enough to do so.

Level	Message	Meaning
Text (4)	Redundant Text	Generated for vacuous comments like "Returns the component name" for a method named "getComponentName". On the one hand, the extreme redundancy of the comment renders it meaningless, because no additional information is provided. On the other hand, when DocCheck generates a comment template, this is exactly the kind of text it produces! In general, there is a tradeoff between requiring comments to be present on all methods, and requiring the comments to say something interesting. (Sometimes, there simply isn't anything useful to say!) The `-evident` command line switch was added for that reason, so that missing comments which are "self-evident"could be downgraded to a lower error level.

Severity 1	Package, interface, (outer) class, or exception missing comments.
Severity 2	Inner class, inner interface, field, constructor, or method missing a comment. (When the required comment is so obvious that it can be automatically generated from the name of the method, as for example, `getComponentColor()`, the severity level can be reduced using the `-evident` switch.)
Severity 3	Tag errors caused by missing, incomplete, or extraneous tags. Produces tag templates suitable for cutting and pasting. For example: * @param foo an int specifying the ... value
Severity 4	Text errors and link errors. Text errors are caused by unterminated HTML tags or a missing period in the first sentence of a comment, or by unterminated HTML tags anywhere in the body of the comment. Link errors are caused by missing @see links. Note: The body of the comment is only checked if the first sentence was ok. The reason: if the first sentence contains something like "This method does: <ul> <li>one thing." Then this "first sentence" will contain unterminated html (ul and li). To check the "body" would now produce spurious errors. But to check the whole comment would duplicate real errors in the first sentence (for example, an unclosed bold tag). So DocCheck punts. Moral: Run DocCheck multiple times, until no errors occur. Then you know your API comments are clean.
Warning	Generated for methods without comments that override a superclass method or implement an interface. Such methods need no comments, because it will be inherited. A warning is generated though, so the developer can check to see that a normal comment of the form `// Inherited {<from>}` is included in the code. Can also be the level assigned to "self-evident" comments using the `-evident` switch. May be used in the future.