Please review: JBS: https://bugs.openjdk.java.net/browse/JDK-8216497 Webrev: http://cr.openjdk.java.net/~hannesw/8216497/webrev.00/ CSR: https://bugs.openjdk.java.net/browse/JDK-8251181
Most of the new code is added to the Extern class where it fits in quite nicely and can use the existing supporting code for setting up external links. The default behaviour is to generate links to docs.oracle.com for released versions and download.java.net for prereleases. Platform documentation URLs can be configured using the new --link-platform-properties <url> option to provide a properties file with URLs pointing to to alternative locations. See the CSR linked above for more details on the new options. The feature can be disabled using the --no-platform-link option, generating the same output as previously. One problem I had to solve was how to handle the transition from prerelease versions to final releases, since the location of the documentation changes in this transition. For obvious reasons we don’t want to make that switch via code change at a time shortly before release. The way it is done is that we determine if the current javadoc instance is a prerelease version as indicated by the Version returned by BaseConfiguration#getDocletVersion(), and then check whether the release/source version of the current javadoc execution uses the same (latest) version. This means that that only the latest version will ever generate prerelease links (e.g. running current javadoc 16 with source version 15 will generate links to the final release documentation) but I think this is acceptable. Another issue I spent some time getting right was tests. New releases require a new element-list resource*), so tests have to pick up new releases. On the other hand, we don’t want hundreds of tests to fail when a new release is added, ideally there should be one test with a clear message. Because of this, when a release is encountered for which no element-list is available a warning is generated instead of an error, and the documentation is generated without platform links as if running with --no-platform-link option. This allows most existing tests to pass and just the new test to fail with a relatively clear message of what is wrong. *) I also thought about generating the element-list for the current release at build time. It’s quite involved, and we still need to maintain element-lists for older versions, so I’m not sure it’s worth it. For existing tests that check output affected by the new option I added the --no-platform-link option to disable the feature. Otherwise we’d have to update those tests with each new release (or else freeze the tests to use some static release or source version, which we don’t want either). I updated the CSR to the new code. It also needs to be reviewed. Thanks, Hannes
