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

Erik Joelsson erik.joelsson at oracle.com
Wed Oct 26 12:31:17 UTC 2016


Looks good in general.

* The REGEXP parameter is weirdly named. I realize you didn't introduce 
this name, but I think we should call it something better since it's 
clearly not a regular expression. PACKAGE_FILTER perhaps?

* Looks like an extra space on line 346.

* Missing space on 751, 767 (looks like a copy paste mistake that is 
probably present in more places)

* What's the motivation for using = in spec.gmk.in?


On 2016-10-26 13:55, Magnus Ihse Bursie wrote:
> 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

More information about the build-dev mailing list