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
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8168772-clean-up-javadocs/webrev.01/
/Magnus
