JDK-8274926 : No way to locally suppress doclint warnings
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 18
  • Submitted: 2021-10-07
  • Updated: 2022-01-21
  • Resolved: 2021-10-12
Related Reports
CSR :  
JDK-8189591 - No way to locally suppress doclint warnings
Relates :  
JDK-8280488 - doclint reference checks withstand warning suppression
Description
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](https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#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_ <br> where _LIST_ is a comma-separated list of one or more of<br>
   `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.
Comments
Moving to Approved.
12-10-2021
> How will this change be documented, updating the usage output of javac, javadoc, and associated man pages? That's a previously unsolved problem: doclint is currently documented on both the `javac` and `javadoc` man pages, and should be reorganized, but there are some issues that need to be addressed. The core functionality of how to check comments is the same (it's shared code), but the invocation and which comments are checked varies for the two tools. The working hypothesis is to document the tool-specific details on each tool's man page, and find a place to provide more details on the shared functionality. This may best be placed on the `javadoc` man page, but there is no convenient way (other than descriptive text) to link from one man page to another. > I assume javac and javadoc will give the annotations similar semantics. Yes, it's handled in shared code. > Also, I assume the usual lexical nesting for scoping of SuppressWarnings will be in force, for example @SuppressWarning("doclint") in a package-info or module-info file will not suppress warnings in the package or module, respectively. Yes, that is the implementation and the intent of the words "lexical nesting". Although the implementation for this use of `@SuppressWarnings` is completely separate from existing use in `javac` for Java warnings, the intent is that the scoping rules should be the same.
12-10-2021
Moving to Provisional, not Approved. How will this change be documented, updating the usage output of javac, javadoc, and associated man pages? I assume javac and javadoc will give the annotations similar semantics. Also, I assume the usual lexical nesting for scoping of SuppressWarnings will be in force, for example @SuppressWarning("doclint") in a package-info or module-info file will *not* suppress warnings in the package or module, respectively.
08-10-2021
[~prappo] [~hannesw] Updated; thanks.
08-10-2021
* Fix the typo in "Compatibility Risk Description": _argument its for_ * Update the JLS link to the latest version https://docs.oracle.com/javase/specs/jls/se17/html/jls-9.html#jls-9.6.4.5 * Fix the ambiguous sentence(s) that were mentioned by Hannes
08-10-2021
The first sentence of the last paragraph is a bit ambiguous: the "only" refers to "suppress", but is likely to be understood as referring to "warnings" in the context of the previous paragraph which talks about warnings and errors. Otherwise looks good to me!
08-10-2021