<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;
mso-fareast-language:EN-US;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span lang="EN-US">Hi Jon,<o:p></o:p></span></p>
<p style="margin-left:.5in"><span lang="EN-US">Is there a reason why you are using a newer version of javadoc, but wanting to use `--source 8` and link to older versions of the JDK API?<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US">Let’s say, there is a library is being developed for further use with another Java8 project. The library development is performed using Java17 because of some legacy reasons. And these are the reasons of the developers
have no option to choose another version of Java. The library is compiled with ‘-source 8’ or ‘--release 8’ options passed to both javac and javadoc (linking with Oracle’s Java8 docs with ‘-link’ option). As the result, the generated docs are not compatible
with Oracle’s Java8 docs because of different forms of anchors and element IDs. <o:p>
</o:p></span></p>
<p class="MsoNormal"><span lang="EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US">Even if there is a solution to additionally process external links to docs.oracle.com fixing anchors, the generated docs are still not compatible with any other documentation generated with Java8, local or external.<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US">Of course, there are possible workarounds for the scenario above, however this example scenario shows that javac has backward compatibility to lower versions, but javadoc has not.
<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span lang="EN-US">Best regards,<o:p></o:p></span></p>
<p class="MsoNormal"><span lang="EN-US">Roman<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span lang="EN-US" style="mso-fareast-language:#1000">From:</span></b><span lang="EN-US" style="mso-fareast-language:#1000"> Jonathan Gibbons <jonathan.gibbons@oracle.com>
<br>
<b>Sent:</b> Tuesday, November 22, 2022 4:18 AM<br>
<b>To:</b> Roman Marchenko <rmarchenko@azul.com>; javadoc-dev@openjdk.org<br>
<b>Subject:</b> Re: [External] : RE: Docs generated by Java8 Javadoc are incompatible with "javadoc -source 8"<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p><o:p> </o:p></p>
<div>
<p class="MsoNormal">On 11/20/22 11:59 PM, Roman Marchenko wrote:<o:p></o:p></p>
</div>
<blockquote style="margin-top:5.0pt;margin-bottom:5.0pt">
<p class="MsoNormal"><span lang="EN-US">Hi Jon,</span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">Thank you for the answer.</span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">I'm wondering if it's possible to implement support for 'old' form of anchors while generating docs with '-source 8' option to make the docs compatible with Java8 docs. I guess this would make many people (which had issues
with docs compatibility before, but didn't say about it) happy. Do you think it is a bad idea? Will it interfere the ongoing work of standardization?</span><o:p></o:p></p>
</blockquote>
<p>It's philosophically wrong to leverage the input language version to control the output version. See my earlier example, comparing this to javac's `--source` and `--target` option.<o:p></o:p></p>
<p>If this were to be supported at all, it would have to be done differently, such as with new command-line options if so required. The problem is not easy, because it would involve consideration of the form of anchors being created for the declarations being
documented, and the form of anchors being used for the documentation being linked to. At best, it might be reasonable to use the old form of anchors for existing documentation that has already been generated by older versions of javadoc, but I don't think
it is reasonable to use the old form of anchors in newly generated documentation.<o:p></o:p></p>
<p><o:p> </o:p></p>
<blockquote style="margin-top:5.0pt;margin-bottom:5.0pt">
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">There is another question related to this topic. It seems like Javadoc v11...15 cannot generate links to the external docs.oracle.com/javase/8/docs/api at all. So docs generated using ''-source 8' have no links to external
documentation. There is JDK-8216497 which, I guess, fixed this for later versions, but I don't understand why it's not backported below. Are there any reasons to block backporting this to lower versions?</span><o:p></o:p></p>
</blockquote>
<p>Not all features (or bug fixes) get backported. Resources are always an issue.
<span lang="EN-US">JDK-8216497 was a significant feature that required non-trivial build system changes, to make available the information about the platform declarations in earlier releases. That seems like too much to backport.</span><o:p></o:p></p>
<p><o:p> </o:p></p>
<blockquote style="margin-top:5.0pt;margin-bottom:5.0pt">
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">Of course, the problems above don't seem significant, however Javadoc seems inconsistent for now. So, I think, it'd be good to make it fixed if possible.</span><o:p></o:p></p>
</blockquote>
<p><o:p> </o:p></p>
<p>At a minimum, it should be possible to use generate documentation linking to the standard docs at
<span lang="EN-US">docs.oracle.com/javase/8/docs/api, using the `-link` or `linkoffline` options. That would be technically independent of the setting of the `--source` option. If that's not currently possible, that could be in the grey area
<br>
between a bug and an enhancement, and maybe worth investigating.</span><o:p></o:p></p>
<p><span lang="EN-US">Is there a reason why you are using a newer version of javadoc, but wanting to use `--source 8` and link to older versions of the JDK API?</span><o:p></o:p></p>
<p><span lang="EN-US">-- Jon</span><o:p></o:p></p>
<p><o:p> </o:p></p>
<blockquote style="margin-top:5.0pt;margin-bottom:5.0pt">
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">Best regards,</span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">Roman</span><o:p></o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span lang="EN-US" style="mso-fareast-language:#1000">From:</span></b><span lang="EN-US" style="mso-fareast-language:#1000"> javadoc-dev
</span><a href="mailto:javadoc-dev-retn@openjdk.org"><span lang="EN-US" style="mso-fareast-language:#1000"><javadoc-dev-retn@openjdk.org></span></a><span style="mso-fareast-language:#1000">
<b><span lang="EN-US">On Behalf Of </span></b><span lang="EN-US">Jonathan Gibbons<br>
<b>Sent:</b> Friday, November 18, 2022 8:30 PM<br>
<b>To:</b> </span></span><a href="mailto:javadoc-dev@openjdk.org"><span lang="EN-US" style="mso-fareast-language:#1000">javadoc-dev@openjdk.org</span></a><span lang="EN-US" style="mso-fareast-language:#1000"><br>
<b>Subject:</b> Re: Docs generated by Java8 Javadoc are incompatible with "javadoc -source 8"</span><o:p></o:p></p>
</div>
</div>
<p class="MsoNormal"> <o:p></o:p></p>
<p>Hi Roman,<o:p></o:p></p>
<p>TL;DR: The behavior is as expected.<o:p></o:p></p>
<p>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.<o:p></o:p></p>
<p>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.<o:p></o:p></p>
<p>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.<o:p></o:p></p>
<p>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.<o:p></o:p></p>
<p>-- Jon<o:p></o:p></p>
<div>
<p class="MsoNormal">On 11/18/22 7:32 AM, Roman Marchenko wrote:<o:p></o:p></p>
</div>
<blockquote style="margin-top:5.0pt;margin-bottom:5.0pt">
<p class="MsoNormal">Hi,<o:p></o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
<p class="MsoNormal">As far as I know<span lang="EN-US">,</span> 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
<span lang="EN-US">which </span>check<span lang="EN-US">s </span>if Html5-like anchors are generated for “-source 8” option.<o:p></o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
<p class="MsoNormal">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
<span lang="EN-US">(I guess starting from jdk17 and above)</span> “Javadoc -release 8” because they use different types of anchors.
<span lang="EN-US">So it’s impossible to use cross links in such cases.</span><o:p></o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">I haven’t found any discussion explaining that, so could anyone explain, please, if it is correct behavior or not?</span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US"> </span><o:p></o:p></p>
<p class="MsoNormal"><span lang="EN-US">- Roman</span><o:p></o:p></p>
<p class="MsoNormal"> <o:p></o:p></p>
</blockquote>
</blockquote>
</div>
</body>
</html>