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

[Jonathan Gibbons]

Hi Roman,

TL;DR: The behavior is as expected.

If nothing else, note that `--source` describes the language level of 
the input source code, and has no relationship whatsoever to HTML 
version used for the output. This is somewhat similar to javac, where 
`--source` specifies the version of the input source files, and 
`--target` specifies the classfile version of the generated class files.

There are other major differences between JDK 8 javadoc and more recent 
versions.  More obvious than the version of HTML, there is the 
difference in the page layout: JDK 8 javadoc uses frames and predates 
the Search facility; later versions do not use frames, and provide the 
Search mechanism and more in-page links to aid with navigation.

The issue of the form of anchors generated by different versions is an 
interesting special case, with no easy solution at this time, other than 
to use compatible versions of javadoc for the API being cross-linked. 
There is no information available to the `-link` or `-linkoffline` 
options to know the form of anchors used in the documentation being 
linked to.

That being said, there is ongoing work to standardize _and specify_ the 
form of anchors and major structural elements to mitigate against 
problems going forward.

-- Jon

On 11/18/22 7:32 AM, Roman Marchenko wrote:
>
> Hi,
>
> As far as I know, Html4 support was removed from Javadoc a time ago. 
> So now Javadoc generates html5-like anchors even with “-source 8” or 
> “-release 8” option specified. There is JDK-8187521 added 
> TestAnchorNames.testHtml5 which checks if Html5-like anchors are 
> generated for “-source 8” option.
>
> On the other hand, Java8’s Javadoc still supports html4 and doesn’t 
> support html5. So it turns that docs generated by Java8’s Javadoc are 
> not compatible with docs generated by any other (I guess starting from 
> jdk17 and above) “Javadoc -release 8” because they use different types 
> of anchors. So it’s impossible to use cross links in such cases.
>
> I haven’t found any discussion explaining that, so could anyone 
> explain, please, if it is correct behavior or not?
>
> - Roman
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20221118/b8445992/attachment-0001.htm>