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

[Erik Joelsson]

Looks good.

/Erik


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