FYI, coming soon: doclint checking of references

joe darcy joe.darcy at
Mon Jul 13 17:31:04 UTC 2015


FYI, checking the doclint "reference" category is now enabled in the 
docs build:

     8080722: Revisit how to check for doclint reference warning during 
the build

When making javadoc changes, please run a docs build before pushing to 
avoid introducing build breakage.



On 6/26/2015 8:45 PM, joe darcy wrote:
> 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,"
> [2] JDK-8075771: Enable "missing" doclint check in build of the 
> java.desktop module,
> [3] JDK-8080722: Revisit how to check for doclint reference warning 
> during the build,
> [4] JDK-8129909: Add -Xdoclint/packages: to javadoc,

More information about the jdk9-dev mailing list