On Tue, 15 Sep 2020 11:30:09 GMT, Jan Lahoda <jlah...@openjdk.org> wrote:
>> 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 > > I think it would be awesome if we could generate (most of) the > {element,package}-list-VERSION.txt from the ct.sym > historical data at build time. This would (hopefully) help with long-term > maintenance. I've started to sketch that > here: > https://github.com/lahodaj/jdk/commit/36c1510587a4b050b148eda87ae7a7a89aff9690 > Some comments on the attempt: > -in this PR, there is package-list-9.txt - should it be element-list-9.txt, > and should it contain module names (dtto > element-list-10.txt)? > -we may (for historical reasons) want to keep the lists for 7, 8, 9 and 10 > (as the historical data in ct.sym do not > exactly match what is in the package/element lists). It would be better to > generate everything, but having a fixed list > for some of the past versions would be better than having to create a new > list for each new release. > -the patch does not yet generate the list for the current release, but that > should be doable. Thanks for the suggestions and help, Jan! > I think it would be awesome if we could generate (most of) the > {element,package}-list-VERSION.txt from the ct.sym > historical data at build time. This would (hopefully) help with long-term > maintenance. I've started to sketch that > here: > [lahodaj@36c1510](https://github.com/lahodaj/jdk/commit/36c1510587a4b050b148eda87ae7a7a89aff9690) I agree files should be generated dynamically. I knew about the sym files but wasn't sure how to go about it. Thanks a lot for stepping in and helping out, it's very much appreciated! > Some comments on the attempt: > -in this PR, there is package-list-9.txt - should it be element-list-9.txt, > and should it contain module names (dtto > element-list-10.txt)? Javadoc in 9 still uses the old package-centric layout (package-list and no module names in URL paths). It only became fully module-aware in 10. > -we may (for historical reasons) want to keep the lists for 7, 8, 9 and 10 > (as the historical data in ct.sym do not > exactly match what is in the package/element lists). It would be better to > generate everything, but having a fixed list > for some of the past versions would be better than having to create a new > list for each new release. > -the patch does not yet generate the list for the current release, but that > should be doable. I definitely agree. I'll work on a new version that generates as much of the lists as possible. ------------- PR: https://git.openjdk.java.net/jdk/pull/171