RFR: JDK-8189056 javadoc target for stable specdiff comparisons

[Magnus Ihse Bursie]

On 2017-10-19 16:13, Erik Joelsson wrote:
> I believe this looks good for generating the docs. For consumption, we 
> also need to define a new bundle and configure Jib to upload it.

Functionality for bundling and uploading these "reference" docs would 
probably be a good thing to have, but I it's kinda out of scope for this 
bug. The functionality needed is the ability to locally generate docs 
and compare them with specdiffs, similar to how the "docs-javase" target 
works today.

With the new docs-reference target, I agree that it makes more sense to 
produce a bundle to upload. But then again, maybe such a step should 
automatically run specdiff as well.

/Magnus

>
> /Erik
>
>
> On 2017-10-19 14:30, Magnus Ihse Bursie wrote:
>> From the bug report: "For JSR 383 (Java SE 18.3), we need weekly 
>> diffs of the Java SE 18.3 API specification. The current "doc-javase" 
>> makefile target always uses the most recent version of the javadoc 
>> tool (i.e. the tool that was just built). Unfortunately, this 
>> introduces unwanted diffs that are due to changes in the javadoc 
>> tool's formatting of the specification. A means to use a fixed 
>> version of the javadoc tool so that the only detected changes are 
>> those to the specification itself is needed."
>>
>> I have introduced a new class of documentation, "docs-reference", 
>> that will create up-to-date javadoc using the Boot JDK javadoc, and a 
>> fixed set of options.
>>
>> Note that this bug is blocked on JDK-8189094 (Change required boot 
>> jdk to JDK 9). I will await that patch to enter jdk10/master before 
>> pushing this, but my preliminary testing indicates that there will be 
>> no issues. (However, with JDK 8 as Boot JDK, this will not work, 
>> since the command line options is not accepted by JDK 8 javadoc.) If 
>> it turns out that more fixing is needed, I'll reiterate this review 
>> before pushing.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8189056
>> WebRev: 
>> http://cr.openjdk.java.net/~ihse/JDK-8189056-reference-javadoc/webrev.01
>>
>> /Magnus
>