RFR: JDK-8189056 javadoc target for stable specdiff comparisons

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

RFR: JDK-8189056 javadoc target for stable specdiff comparisons

Magnus Ihse Bursie
 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
Reply | Threaded
Open this post in threaded view
|

Re: RFR: JDK-8189056 javadoc target for stable specdiff comparisons

Erik Joelsson
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.

/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

Reply | Threaded
Open this post in threaded view
|

Re: 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
>