RFR: 8216497: javadoc should auto-link to platform classes [v4]

Hannes Wallnöfer hannesw at openjdk.java.net
Wed Oct 7 12:42:32 UTC 2020

> 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

Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev
excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since
the last revision:

 - Fix test failure
 - Merge branch 'master' into JDK-8216497
 - Rename --no-platform-link option plus minor cleanup
 - Merge pull request #1 from lahodaj/JDK-8216497
   Automatically generate the elements-list data from the ct.sym for releases 11+, including the current release under
 - Generating current release list for javadoc; using hardcoded lists for versions < 11
 - Attempting to (mostly) generate the javadoc release manifests from ct.sym historical data.
 - 8216497: javadoc should auto-link to platform classes


  - all: https://git.openjdk.java.net/jdk/pull/171/files
  - new: https://git.openjdk.java.net/jdk/pull/171/files/6009dd70..991daef5

 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=171&range=03
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=171&range=02-03

  Stats: 69874 lines in 2995 files changed: 23958 ins; 34697 del; 11219 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

More information about the compiler-dev mailing list