Summary

Leverage the @SuppressWarnings mechanism to suppress warnings generated by DocLint.

Problem

javac and javadoc provide support for checking the content of documentation comments. Some limited capability is provided by command-line options to control which checks are enabled, but in conjunction with other options, these options apply to all comments being checked, with no way to disable warnings in specific documentation comments.

Solution

The standard way to suppress warnings in javac is by using the @SuppressWarnings mechanism, defined in JLS 9.6.4.5. The annotation does not define the set of strings that may be recognized, with the implication that additional strings may be added and recognized over time.

DocLint is enhanced to recognize new strings, pertaining to the warnings and errors that may be reported regarding issues in documentation comments.

Specification

DocLint checks for and recognizes two strings that may be present in the arguments for an @SuppressWarnings annotation.

• doclint
• doclint:LIST
  where LIST is a comma-separated list of one or more of
  accessibility, html, missing, syntax, reference.

The names in LIST are the same "group" names supported by the command-line -Xdoclint option for javac and javadoc. Note: This is the same convention honored by the javac -Xlint option and the corresponding names supported by @SuppressWarnings.

When DocLint detects an issue in a documentation comment, it checks for the presence of @SuppressWarnings on the associated declaration and on all lexically enclosing declarations. The issue will be ignored if any annotation is found containing the simple string "doclint" or the longer form "doclint:LIST" where LIST contains the name of the group for the issue.

DocLint may report errors as well as warnings. All messages related to an issue are suppressed by the presence of an appropriate @SuppressWarnings annotation: this includes errors as well as warnings.

Note: It is only possible to suppress messages. If an annotation of @SuppressWarnings("doclint") is given on a top-level declaration, all DocLint messages for that declaration and any enclosed declarations will be suppressed; it is not possible to selectively re-enable messages for issues in enclosed declarations.