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

[Magnus Ihse Bursie]

On 2016-10-26 14:31, Erik Joelsson wrote:
> Hello,
>
> 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):
http://cr.openjdk.java.net/~ihse/JDK-8168772-clean-up-javadocs/webrev.02

/Magnus

>
> /Erik
>
> 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
>