Hi Jon,
Is my understanding correct that 'platform links' supposed to be also checked
for presence of package-list or element-list?
I mean there is the 'platform link' depends on JDK version number or
release/source option value. The list of platform elements is contained in
'hard-coded' JDK txt files, so processing platform elements doesn't require
internet connection, regardless of it was replaced with
'link-platform-properties' option or not. In case it needs to be checked for
element-list presence, it may require internet connection.
On the other hand, it would be much easier to hardcode type of anchors for
'platform' links, since it's not supposed to rebuild platform docs.
Best regards,
Roman
-----Original Message-----
From: Jonathan Gibbons <[email protected]>
Sent: Thursday, January 5, 2023 2:32 AM
To: Roman Marchenko <[email protected]>; Hannes Wallnoefer
<[email protected]>
Cc: [email protected]
Subject: Re: [External] : RE: Docs generated by Java8 Javadoc are incompatible with
"javadoc -source 8"
Roman,
For the main issue in your email, there is no reasonable general solution.
[But, see a suggestion below].
The underlying problem is that there was a series of releases where some
incompatible changes were made, for the best of reasons, in the form of the
names used for anchors/ids.
In JDK 7, the output format was HTML, but the anchors were unencoded, and even
included whitespace characters, and thus reported as invalid by HTML syntax
checkers, such as `HtmlTidy`.
In JDK 8, the anchors were encoded, so that the generated HTML files could be
validated for conformance.
In JDK 9, HTML 5 became an option, allowing the use of unencoded anchors again
(without whitespace)
In JDK 11, HTML 5 became the default, with an unsuppressable warning given if
HTML 4 was requested.
In JDK 13, support for HTML 4 was removed, and thus all output was HTML 5, with
legal/unencoded anchors.
Throughout this transition period, there was nowhere to easily record the form
of the anchors used in the generated documentation, leading to the kind of
compatibility problems we are discussing here.
So, the problem primarily exists when trying to link to older API. Docs
generated with JDK 7 are not interesting, because the release is no longer
supported, and the docs were generally broken/invalid. Docs generated with
JDK 8 are potentially of interest, because it is still a supported version.
Docs generated with 9 and 10 are less interesting just because those are older
releases that are no longer supported, although I accept that support (or lack
thereof) for the JDK version does not imply support (or lack thereof) for
unrelated end-user libraries.
So, to summarize, I do think that the presence of package-list or element-list is a
reasonable default proxy to indicate the style of anchors in generated documentation,
even if it is not always 100% accurate. I agree with your sentiment that it is not
reasonable to grovel through files looking for anchors, although it might be interesting
to see how much you could infer from a standard file in any generated API, like
`index.html`. That leaves only one option (sic) which would be to either provide a new
command-line option to specify the encoding used for anchors/ids in any given API, or to
enhance the existing `-link`/`-linkoffline` options to allow that information to be
provided. But, while I think it is reasonable to provide the ability to link to APIs
generated with JDK 8, I'm not sure it is worth the effort to be able to link to API
documentation generated with other older releases that are no longer supported. Ideally,
those libraries should be using supported JDK releases, and the package-list/element-list
trick will be "good enough".
-- Jon
On 12/27/22 2:28 AM, Roman Marchenko wrote:
Hi Jon and Hannes,
Thank you for reviewing my proposal. As far as I understand, it's suggested to use
element/package-list file presence rather than using "-source" option to determine a type
of anchors. This is needed because there are docs generated by some "recent" code, so, in
case of a fix, we would like to keep backward compatibility and satisfy all the cases.
I tried some experiments with javadoc and 3rd party libs, and I've found Dagger
library. Its docs are located
herehttps://urldefense.com/v3/__https://dagger.dev/api/2.0/__;!!ACWV5N9M2RV99hQ!PSu9axKvSpAzp-jvCGznT0naE57tmmB9s9GVHwG1QgKm-FGttuG-Ai-6lp_sXSCo8hy2GM-CVycT1ZA3bkxJLYau$
.
Dagger docs contain "package-list" file. Additionally, headers of html files contain "HTML 4"
marks. However, all its anchors are "new" style,
e.g.https://urldefense.com/v3/__https://dagger.dev/api/2.0/dagger/Lazy.html*get()__;Iw!!ACWV5N9M2RV99hQ!PSu9axKvSpAzp-jvCGznT0naE57tmmB9s9GVHwG1QgKm-FGttuG-Ai-6lp_sXSCo8hy2GM-CVycT1ZA3bpT3Hn7j$
. I have no idea how it could happen. Is this case a kind of a bug or was it generated by some "legal"
version of javadoc we need to support? Perhaps it could be analyzed through all the pages to find a link to any class
method to determine a type of anchors, but, I guess, this approach is too complicated.
