On 11/20/22 11:59 PM, Roman Marchenko wrote:
Hi Jon,
Thank you for the answer.
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?
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.
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.
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?
Not all features (or bug fixes) get backported. Resources are always an
issue. 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.
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.
At a minimum, it should be possible to use generate documentation
linking to the standard docs at 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
between a bug and an enhancement, and maybe worth investigating.
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?
-- Jon
Best regards,
Roman
*From:*javadoc-dev <[email protected]> *On Behalf Of
*Jonathan Gibbons
*Sent:* Friday, November 18, 2022 8:30 PM
*To:* [email protected]
*Subject:* Re: Docs generated by Java8 Javadoc are incompatible with
"javadoc -source 8"
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
