JDK-8189591 : No way to locally suppress doclint warnings
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 15
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2017-10-17
  • Updated: 2022-01-06
  • Resolved: 2021-10-16
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 18
18 b20Fixed
Related Reports
Blocks :  
JDK-8164408 - Add module support for @see, @link and @linkplain javadoc tags.
CSR :  
JDK-8274926 - No way to locally suppress doclint warnings
Relates :  
JDK-8224228 - No way to locally suppress lint warnings in parser/tokenizer or preview features
Relates :  
JDK-8235721 - Enhance support for SuppressWarnings
Relates :  
JDK-8042878 - JEP 212: Resolve Lint and Doclint Warnings
Sub Tasks
JDK-8275351 :  
Release Note: @SuppressWarnings for DocLint messages - Resolved
Description
Most lint warnings are suppressible with a suitable invocation of @SuppressWarnings, which allows you to get the benefit of full checking while allowing specific false positives to be suppressed.  However, there is no such category for doclint-generated warnings.  Suggest supporting @SuppressWarnings("doclint").
Comments
Changeset: 96fef40b Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2021-10-16 03:04:11 +0000 URL: https://git.openjdk.java.net/jdk/commit/96fef40b8206c7027c6688bc0cb0bd979bea4b4b
16-10-2021
In doclint, it is not particularly hard to detect and track instances of @SuppressWarnings on declarations and any enclosing classes and interfaces. The proposed set of supported arguments for @SuppressWarnings is * doclint suppress all doclint warnings * doclint:<name> where <name> is one of "accessibility", "html", "missing", "reference", "syntax" suppress warnings in a given group By analogy with javac -Xlint, the names are the exact same names as can be used on the command line in -Xdoclint options.
13-08-2021
On the subject of doclint being able to track SuppressWarnings... In javac, the doclint TaskListener can track which source files are being read, and can then subsequently scan the corresponding elements looking for @SuppressWarnings annotations, looking for ones beginning "doclint:.*" In javadoc, there's no task listener, but everything is driven by elements, so we have access to the annotations on those elements ts and their enclosing elements. In both cases, we may need to extend doclint to support a filter (Predicate?) to determine whether individual messages should be reported or not. There's a related bigger problem of somewhat widespread missing comments: does this all become a way to sweep those messages "under the carpet"?
22-06-2020
While it would be "nice" to have doclint reference checking turned on at compile time, if the modules are not on the (module) source path, that is potentially a big deal. But, we can always enable doclint at javadoc time, when all the modules being documented should inherently be available.
27-11-2018
We should probably break this into two separate parts. 1. Have DocLint keep track of which warnings have been suppressed. 2. Increase the resolution for all lint-like warnings.
11-01-2018
The lingering issues with doclint reference checks and modules is compiling @see/@link reference from, say, the java.base module into, for example, java.desktop. Modules other than java.base and not around or allowed by java.base is being compiled, but the links are fine in the eventual docs build. If the handful of situations like this could be suppressed, we could get general doclint reference checking enabled in more of the build.
17-10-2017
I agree that we want finer granularity than just "doclint". If there is a perceived need to disable the reference check, we should see if there is an underlying bug. It ought to be the case that all references are "good".
17-10-2017
If finer granularity is needed, a natural extension would be "doctlint:$CATEGORY" for the various categories, accessibility, HTML, missing, reference, and syntax. Being able to selectively disable the reference check in a handful of cases would allow larger portions of the sources to be covered by doclint.
17-10-2017