FYI, coming soon: doclint checking of references

[joe darcy]

Hello,

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
     http://hg.openjdk.java.net/jdk9/dev/rev/bea3a9e40c23

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

Thanks,

-Joe

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,"
> 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