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.
