[External] : RE: Docs generated by Java8 Javadoc are incompatible with "javadoc -source 8"

[Jonathan Gibbons]

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.