RFR: 8248409, 8248417 Dotted version numbers in javadoc

[Jonathan Gibbons]

Agreed on updating the doc comment.

Thanks.

-- Jon

On 6/29/20 4:44 AM, Pavel Rappo wrote:
> Jon,
>
> Consider retaining that example string with pre-release information in the doc comment for Versions#shortVersionStringOf(): "15-internal"; I think this is useful for illustrative purposes.
>
> Other than that, those patches look good. Thanks.
>
> -Pavel
>
>> On 26 Jun 2020, at 23:04, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Please review together two fixes for two related bugs.  One fix is for JDK 15, the other for 16.
>>
>> As background, there have been two recent updates to javadoc:
>>
>> 	• JDK 15: Use Runtime.Version to represent javadoc and doclet versions
>> 	• JDK 16: Always include the javadoc (feature) version in the metadata in each generated HTML file
>> The problem, for both, is when the version string has more than one numeric component
>> i.e. an update or patch number as well as the initial feature number. For example, 16.0.0.1.
>> This issue is reported in https://bugs.openjdk.java.net/browse/JDK-8248409
>>
>> In the case of #1, `javadoc --version` only reported the feature version and prerelease info
>> (e.g. 16-internal) and not the full version number.  The intent/spec is that it should generally
>> match the number(s) given in `java --version` and `javac --version`.
>>
>> In the case of #2, the metadata included additional info when it was not intended to.
>>
>> In JDK 15, the fix is:
>>
>> 	• in Versions.java, use all the components of the version number, and not just the feature number
>> 	• in Head.java, pass in a Runtime.Version instead of a String, and then explicitly select the
>> feature component
>> 	• in BaseConfiguration.java, remove getDocletVersionString() which is now unused
>> Webrev: http://cr.openjdk.java.net/~jjg/8248409/webrev.00/
>>
>>
>> The patch for 15 causes merge conflicts for 16. A patch showing the result of resolving the
>> merge conflicts is provided here:
>> http://cr.openjdk.java.net/~jjg/8248417/after-merge.patch
>>
>>
>>
>> In JDK 16, the doclet feature version is always written out, instead of being subject to
>> the `-notimestamp` option. When the patch for 8248409 is merged into 16, the test
>> for the new metadata will fail because of a bug in the test that was (up to now) cancelled
>> out by the issue in 8248417.  The fix for the test is trivial, to use `java.specification.version`
>> instead of `java.version`.
>>
>> Webrev: http://cr.openjdk.java.net/~jjg/8248417/webrev.00
>>
>> Note that this patch can safely be applied to JDK 16 before the patch for 8248409.
>> Doing so will prevent a test failure in 16 after the fix for 8248409 is merged and before
>> this patch is applied.  The patch is safe to apply earlier because in our CI EA builds,
>> java.version == java.specification.version, and so the test will not fail.
>>
>> After both patches have been applied, all javadoc tests should pass in both 15 and 16
>> when additional numeric components in the version number are present.
>>
>> -- Jon
>>
>>   
>>
>>
>>
>>
>>
>>