RFR: 8248409, 8248417 Dotted version numbers in javadoc

[Jonathan Gibbons]

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:

 1. JDK 15: Use Runtime.Version to represent javadoc and doclet versions
 2. 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





-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200626/406e5986/attachment-0001.htm>