RFR: 8248409, 8248417 Dotted version numbers in javadoc

[Pavel Rappo]

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