RFR: 8216497: javadoc should auto-link to platform classes

[Hannes Wallnöfer]

This pull request is identical with the RFR previously sent for the Mercurial repository:

https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html

I'm copy-pasting the comments from the original RFR below.

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:
https://bugs.openjdk.java.net/browse/JDK-8251181

Thanks,
Hannes

-------------

Commit messages:
 - 8216497: javadoc should auto-link to platform classes

Changes: https://git.openjdk.java.net/jdk/pull/171/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=171&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8216497
  Stats: 3230 lines in 53 files changed: 3220 ins; 4 del; 6 mod
  Patch: https://git.openjdk.java.net/jdk/pull/171.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/171/head:pull/171

PR: https://git.openjdk.java.net/jdk/pull/171