FYI, coming soon: doclint checking of references

[joe darcy]

Hello,

The last remaining piece of JEP 212: "Resolve Lint and Doclint Warnings" 
is to enable the final doclint warning category "reference," which 
verifies the javadoc tags @see, @link, @throws, and the like have valid 
targets in the API. While the other four categories of doclint warnings 
are already turned on in the javac build of the sources [1] [2], the 
reference category cannot be enabled at present in the javac build due 
to how the modularized build works. (Briefly, an example of the issue is 
that when building the java.base module, only API references within 
java.base and recognized and javadoc in some java.base types references 
types in other modules.)

To cope with this situation, the "reference" check will instead be 
enabled in the javadoc command. [3] Before that can happen, the javadoc 
command will need a package filter [4] analogous to the doclint package 
filter already in javac. (If such a filter were not added, over 1000 
reference problems in the javadoc of generated corba code would need to 
be addressed!)

Once the doclint check is enabled in the docs build, engineers making 
javadoc changes should run a docs build before doing a push to make sure 
the changes are valid, which is a good practice even today.

Thanks,

-Joe

[1] "javac doclint checking now enabled in the JDK 9 build,"
http://mail.openjdk.java.net/pipermail/jdk9-dev/2015-March/001985.html

[2] JDK-8075771: Enable "missing" doclint check in build of the 
java.desktop module,
https://bugs.openjdk.java.net/browse/JDK-8075771

[3] JDK-8080722: Revisit how to check for doclint reference warning 
during the build,
https://bugs.openjdk.java.net/browse/JDK-8080722

[4] JDK-8129909: Add -Xdoclint/packages: to javadoc,
https://bugs.openjdk.java.net/browse/JDK-8129909