RFR: JDK-8168772 Convert javadoc generation to build-infra standards
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Wed Oct 26 13:22:37 UTC 2016
On 2016-10-26 14:31, Erik Joelsson wrote:
> 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?
You're absolutely right. I didn't think this all the way through,
although I did document it as "package filter". Renamed. :-)
> * 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)
Eagle eye! :-) Fixed all ",\" -> ", \".
> * What's the motivation for using = in spec.gmk.in?
I didn't want to reorder the major blocks in the spec file, so since
OUTPUT dirs are declared above IMAGE dirs, but now the OUTPUT dir is
dependent on the image dir, I could not evaluate it at the moment. Also,
I wanted to fit in the pattern, where OUTPUTDIRs are declared with =
instead of := to be able to work with bootcycle builds. (Not sure it's
relevant for docs, but it should work.)
Updated webrev (changed whitespace and REGEXP -> PACKAGE_FILTER):
> 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
More information about the build-dev