Docs generated by Java8 Javadoc are incompatible with "javadoc -source 8"

[Roman Marchenko]

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 <jonathan.gibbons at oracle.com> 
Sent: Thursday, January 5, 2023 2:32 AM
To: Roman Marchenko <rmarchenko at azul.com>; Hannes Wallnoefer <hannes.wallnoefer at oracle.com>
Cc: javadoc-dev at openjdk.org
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.