JDK-8280488 : doclint reference checks withstand warning suppression
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 18,19
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2022-01-21
  • Updated: 2022-01-31
  • Resolved: 2022-01-31
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 19
19 masterFixed
Related Reports
Blocks :  
JDK-8280492 - Use cross-module syntax for cross-module links
Relates :  
JDK-8274926 - No way to locally suppress doclint warnings
Relates :  
JDK-8164408 - Add module support for @see, @link and @linkplain javadoc tags.
Description
After JDK-8274926, the doclint reference checks are still enabled it the code in question is annotated with @SuppressWarnings("doclint") or @SuppressWarnings("doclint:reference").

This was noticed when @SuppressWarnings("doclint:reference") did not stop doclint errors in the JDK build for cross-module links.
Comments
Changeset: ee3be0bb Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2022-01-31 22:47:46 +0000 URL: https://git.openjdk.java.net/jdk/commit/ee3be0bb567f0e28fd3e920ef3685607d0a8d656
31-01-2022
A pull request was submitted for review. URL: https://git.openjdk.java.net/jdk/pull/7222 Date: 2022-01-26 02:20:24 +0000
26-01-2022
If the module is the same as the package, you ought to be able to go @see name/ i.e. with a trailing '/', (but that might be wishful thinking from other environments.)
24-01-2022
PR of library updates using proposed syntax: https://git.openjdk.java.net/jdk/pull/7189 What is the idiom (if any) to make a @see/@link reference to a module rather than a package? Some modules in the JDK have the same name as a package.
22-01-2022
Sounds good; I'll attach a candidate patch to java.base within the next few days that can be used to help verify the change.
22-01-2022
I'd prefer to stay with the de-facto standard use of '/' to separate module and package name, rather than introduce yet another syntax. But otherwise yes, I agree with the suggestion ... with the refinement that the downgrade only happens if the module is not found in the overall module graph. So, summary, if in java.base you use @see java.desktop/java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter) you'll get a (suppressible) warning in javac but if in java.desktop you use @see java.base/java.lang.NotAnObject you'll (always) get an error ... because the module will be in the module graph
22-01-2022
There are two separate but related issues here, with a variety of possible solutions. Issue #1: the implementation of @SuppressWarnings("doclint") does not match the spec given in the man page and CSR. The implementation just suppresses warnings (but not errors) while the spec says that warnings and errors are suppressed. Issue #2: we want to be able to disable diagnostics for selected references when the target is not available on the class or module path ... while still being able to detect typos in references when it matters. There are two obvious fixes for Issue #1 ... either fix the implementation or fix the spec. The current implementation seems more natural (@SuppressWarnings should just suppress warnings) but the annotation is the only reasonable mechanism we have to provide localized suppression of issues, so if we can't make the errors go away (somehow) we might need to be able to suppress them. For issue #2, there are various possible fixes: Fix #2a: allow @SuppressWarnings("doclint") to suppress errors as well Fix #2b: provide an "sledgehammer" mode to downgrade all doclint errors to warnings when invoked from javac Fix #2c: provide a more precise mode to downgrade issues resulting from cross-module references from errors to warnings when the target module is not in the module graph. This mode might be enabled from javac, but not from javadoc (so that javadoc will still catch issues with mis-spelled module names.) We would need a variant of this rule for non-modular code. If we go with #2b or #2c, then the fix for Issue #1 could be to just update the spec to match the implementation. Overall, the general issue here seems specific to "forward references" when the reference is potentially valid but the target is not on the class path or module path. Accommodating this use case seems the best way to address this problem, while still retaining the ability to post errors for significant issues that are locally fixable. And, (to be clear) if we can find a way to downgrade the forward cross-module references from errors to warnings, they can then be suppressed with @SuppressWarnings.
22-01-2022
Brainstorming suggestion for 2, treat accordingly: allow distinguished syntax for cross-module links. For example, from the base module instead of @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter) to link to a method in java.desktop use @see java.desktop:java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter) When compiling in single module mode, such cross-module links could be skipped other than for syntactic checking, etc.
22-01-2022