RFR: JDK-8168772 Convert javadoc generation to build-infra standards

Magnus Ihse Bursie magnus.ihse.bursie at oracle.com
Wed Oct 26 11:55:11 UTC 2016

The Javadoc generation was never touched by the original build-infra 
conversion project. The Javadoc.gmk file is still a mess of duplicated 
code and ill-defined responsibilities.

For any kind of improvements to be able to happen in the Javadoc area, 
the old codebase needs to be cleaned up and brought in line with the 
rest of the build-infra framework.

For this fix, I have opted to keep the current structure of creating two 
files containing command-line arguments to the Javadoc tool, in 
support/docs/*.packages and support/docs/*.options, and to keep this 
file byte-by-byte identical. This allowed me to keep a high level of 
confidence that no actual changes will be produced in the generated 
Javadoc files. (Due to timestamps and other ephemeral data, direct 
byte-to-byte comparisons is not possible for generated Javadoc). As an 
additional safeguard, I have used our compare script, which filters out 
known volatilities, on selected platforms, and detected no differences.

Once this fix is in, the door is open for more improvements. Some 
examples include:

* Relaxing the requirement for identical *.options/*.packages will allow 
for cleaner code in the makefile
* Allowing the coredocs generation to run concurrently with the other 
javadoc generation
* Unifying the varying options between javadoc runs, which is most 
likely just due to historical accidents, and the old "copy and modify" style
* Simplify future fixes/enhancements to Javadoc

Bug: https://bugs.openjdk.java.net/browse/JDK-8168772


More information about the build-dev mailing list