-
CSR
-
Resolution: Approved
-
P3
-
None
-
behavioral
-
minimal
-
new feature, using a previously unused argument for `@SuppressWarnings`
-
Java API
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.
- csr of
-
JDK-8189591 No way to locally suppress doclint warnings
- Resolved
- relates to
-
JDK-8280488 doclint reference checks withstand warning suppression
- Resolved