Re: RFR: 8216497: javadoc should auto-link to platform classes [v3]
On Wed, 23 Sep 2020 14:20:12 GMT, Hannes Wallnöfer 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 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 incrementally with one > additional commit since the last revision: > > Rename --no-platform-link option plus minor cleanup I agree with the judgement call to _not_ introduce default javadoc options. It was just a suggestion to consider, and I agree it would make the calls less intuitively obvious, for the short term gain of editing fewer tests here. It also helped to realize that the support default platform links does _not_ involve any network access. FWIW, the precedent in JavadocTester that I was referrng to is `setAutomaticCheckLinks`, `setAutomaticCheckAccessibility`, but those are about default actions after javadoc has been run, and not about default methods. - Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v3]
> 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 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 incrementally with one additional commit since the last revision: Rename --no-platform-link option plus minor cleanup - Changes: - all: https://git.openjdk.java.net/jdk/pull/171/files - new: https://git.openjdk.java.net/jdk/pull/171/files/6d659ae3..6009dd70 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=171=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk=171=01-02 Stats: 73 lines in 38 files changed: 0 ins; 0 del; 73 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
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
On Tue, 22 Sep 2020 17:30:19 GMT, Jonathan Gibbons wrote:
>> Hannes Wallnöfer has updated the pull request incrementally with three
>> additional commits since the last revision:
>>
>> - 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
>>development
>> - 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.
>
> test/langtools/jdk/javadoc/doclet/testAnnotationTypes/TestAnnotationTypes.java
> line 49:
>
>> 47: javadoc("-d", "out-1",
>> 48: "-sourcepath", testSrc,
>> 49: "--no-platform-link",
>
> I see lots of instances of `no-platform-link` in this and subsequent tests.
> `JavadocTester` does have the concept of
> default options, although that may be more for the behavior after executing
> javadoc and not for the options given to
> javadoc itself. Is it worth supporting default javadoc options, since that
> the default can be disabled for specific
> tests?
I can't really find how `JavadocTester` uses or supports default options. My
concern with this would be that it would
make JavadocTester less transparent and intuitive to use, as you'd have to be
aware what the default options are.
-
PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
On Mon, 21 Sep 2020 10:47:40 GMT, Hannes Wallnöfer 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 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 incrementally with three
> additional commits since the last revision:
>
> - 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
>development
> - 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.
Generally excellent. Some feedback inline.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
line 350:
> 348:
> 349: doclet.usage.excludedocfilessubdir.parameters=\
> 350: :..
3 dots for ellipsis? 2 dots is "parent directory"
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
line 384:
> 382:
> 383: doclet.usage.no-platform-link.description=\
> 384: Do not generate links to platform documentation
Suggest:
Do not generate links to the platform documentation
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java
line 194:
> 192:
> 193: /**
> 194: * Argument for command-line option {@code --no-platform-link}.
minor: would "--no-platform-links" (plural) be a better name for the option?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java
line 435:
> 433: },
> 434:
> 435: new Option(resources, "--no-platform-link") {
Repeating preceding comment: would `--no-platform-links` (plural) be a better
name?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java
line 236:
> 234: * @param linkPlatformProperties path or URL to properties
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
On Tue, 22 Sep 2020 17:24:19 GMT, Jonathan Gibbons wrote:
>> Hannes Wallnöfer has updated the pull request incrementally with three
>> additional commits since the last revision:
>>
>> - 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
>>development
>> - 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.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java
> line 323:
>
>> 321: props.load(inputStream);
>> 322: }
>> 323: url = props.getProperty("doclet.platform.docs." + version);
>
> Similar to other file-or-url arguments: good!
As a possibly-later cleanup, should we have a single utility method somewhere
(in this class) to open a stream on a
file-or-url?
-
PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
> 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 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 incrementally with three additional commits since the last revision: - 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 development - 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. - Changes: - all: https://git.openjdk.java.net/jdk/pull/171/files - new: https://git.openjdk.java.net/jdk/pull/171/files/2aed84f8..6d659ae3 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=171=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk=171=00-01 Stats: 2007 lines in 9 files changed: 308 ins; 1698 del; 1 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
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 12:56:13 GMT, Erik Joelsson 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 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 > > Build changes look good. Converted to draft as @lahodaj has offered to enhance the feature as described in the comments above. - PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 09:10:54 GMT, Hannes Wallnöfer 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 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 Build changes look good. - Marked as reviewed by erikj (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 11:30:09 GMT, Jan Lahoda 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 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
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 09:10:54 GMT, Hannes Wallnöfer 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 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.
-
PR: https://git.openjdk.java.net/jdk/pull/171
RFR: 8216497: javadoc should auto-link to platform classes
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 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=171=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
