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

[Roman Marchenko]

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 here https://dagger.dev/api/2.0/.
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://dagger.dev/api/2.0/dagger/Lazy.html#get(). 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.

Also there is another minor question. We've got the scenario with URL redirection when URL is not found by a server. For example, URL "https://docs.oracle.com/javase/8/docs/api/element-list" currently will be redirected to "https://docs.oracle.com/en/java/javase/19/" since element-list cannot be found. I suppose it can be processed by detecting that redirection occurred and re-reading the link to find "package-list".

Roman


-----Original Message-----
From: Hannes Wallnoefer <hannes.wallnoefer at oracle.com> 
Sent: Monday, December 12, 2022 5:35 PM
To: Roman Marchenko <rmarchenko at azul.com>
Cc: javadoc-dev at openjdk.org; Jonathan Gibbons <jonathan.gibbons at oracle.com>
Subject: Re: [External] : RE: Docs generated by Java8 Javadoc are incompatible with "javadoc -source 8"

Hi Roman, 

In case you want to refine your fix, I think Jon’s comment on the JBS issue provides a good approach for detecting which format to use:

https://bugs.openjdk.org/browse/JDK-8297437

Package/element lists are read in class `jdk.javadoc.internal.doclets.toolkit.util.Extern`, so I guess this is where you would want to implement this.

Hannes


> On 9 Dec 2022, at 17:51, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Roman,
> 
> You are welcome to file a PR, subject to OCA rules, etc, but that being said, your comparison does not seem like a valid fix for JDK-8297437.
> 
> Once again, I emphasise to you that the `--source` option is not a valid way to determine the output format, as you do in these lines of getValidHtmlName.
> 
> {
> 
> 
>             SourceVersion srcVer = configuration.docEnv.getSourceVersion();
> 
> 
>             if (SourceVersion.RELEASE_8 != srcVer && SourceVersion.RELEASE_9 != srcVer) {
> 
> 
>                 return name;
> 
> 
>             }
> 
> 
>         }
> 
> If nothing else, the code above makes far too simple a choice: the correct choice will depend on the library being linked to.   When running javadoc on some "recent" code, some of the libraries being linked to may have been generated by JDK8-era javadoc (with HTML4-style ids) and others may have been generated by more recent versions of javadoc (with HTML5-style ids).
> 
> -- Jon