<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<p><br>
</p>
<div class="moz-cite-prefix">On 11/20/22 11:59 PM, Roman Marchenko
wrote:<br>
</div>
<blockquote type="cite" cite="mid:DM8PR11MB5736B0302B5D058470E5103EBF0A9@DM8PR11MB5736.namprd11.prod.outlook.com">
<meta name="Generator" content="Microsoft Word 15 (filtered
medium)">
<style>@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;}p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;
mso-fareast-language:EN-US;}span.EmailStyle21
{mso-style-type:personal-compose;
font-family:"Calibri",sans-serif;
color:windowtext;}.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}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]-->
<div class="WordSection1">
<p class="MsoNormal"><span lang="EN-US">Hi Jon,<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">Thank you for the
answer.<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">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></p>
</div>
</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.</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.<br>
</p>
<p><br>
</p>
<blockquote type="cite" cite="mid:DM8PR11MB5736B0302B5D058470E5103EBF0A9@DM8PR11MB5736.namprd11.prod.outlook.com">
<div class="WordSection1">
<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">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></p>
</div>
</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.<br>
</span></p>
<p><br>
</p>
<blockquote type="cite" cite="mid:DM8PR11MB5736B0302B5D058470E5103EBF0A9@DM8PR11MB5736.namprd11.prod.outlook.com">
<div class="WordSection1">
<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">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></p>
</div>
</blockquote>
<p><br>
</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></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?<br>
</span></p>
<p><span lang="EN-US">-- Jon<br>
</span></p>
<p><span lang="EN-US"><br>
</span></p>
<blockquote type="cite" cite="mid:DM8PR11MB5736B0302B5D058470E5103EBF0A9@DM8PR11MB5736.namprd11.prod.outlook.com">
<div class="WordSection1">
<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 style="mso-fareast-language:#1000" lang="EN-US">From:</span></b><span style="mso-fareast-language:#1000" lang="EN-US">
javadoc-dev <a class="moz-txt-link-rfc2396E" href="mailto:javadoc-dev-retn@openjdk.org"><javadoc-dev-retn@openjdk.org></a>
<b>On Behalf Of </b>Jonathan Gibbons<br>
<b>Sent:</b> Friday, November 18, 2022 8:30 PM<br>
<b>To:</b> <a class="moz-txt-link-abbreviated" href="mailto:javadoc-dev@openjdk.org">javadoc-dev@openjdk.org</a><br>
<b>Subject:</b> 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>Hi Roman,<span style="mso-fareast-language:#1000"><o:p></o:p></span></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>
</div>
</blockquote>
</body>
</html>