JDK-8216497 : javadoc should auto-link to platform classes
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2019-01-10
  • Updated: 2021-02-13
  • Resolved: 2020-10-07
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 16
16 b19Fixed
Related Reports
CSR :  
Duplicate :  
Duplicate :  
Relates :  
Relates :  
Sub Tasks
JDK-8261684 :  
It has long been understood that correct use of javac and javadoc `-source` option should be accompanied by an equivalent `-bootclasspath` option ... and equally understood that this is often-times difficult in a development environment, since it requires access to an installed version of the relevant API. This led to the introduction of the `--release` option for both java and javadoc, such that the compilation environment automatically provides access to the appropriate version of the platform classes.

There is a similar issue in javadoc with respect to linking to the API docs for the platform classes. The issue is not as severe (or as well known) as the `-bootclasspath` problem, because it is often common practice to not link to the platform API docs at all, but for those that do want to link to the platform API docs, it is similarly tedious. Either one must have access to the Internet, to use the `-link` option, or one must have access to a local version of the API description file (originally packages.list, now element.list) for the appropriate API. If one uses the `link` option to access the API description file via the Internet, one must deal with the irregularities in the URLs for the API docs for different releases. See, for example, this code in the Maven javadoc plugin, that has to maintain a mapping table:

It would be better if javadoc itself knew the mapping table, and/or provided local copies of the API description files, so that clients did not have to ... whether the clients are running javadoc directly, or via a plugin for a build system like Ant or Maven.

Note ... it should still be possible for a user to override the default location, in the same way that a user can override the location of the compiled platform classes. Such overriding should presumably be done with the existing `-link` or `-linkoffline` options. This implies that javadoc should be able to examine the overall set of `-link*` options, to determine if any of the options provide a URL for the platform classes, such as by looking for a URL for the `java.lang` package. If no such URL is provided, then javadoc can provide a default.

It is arguably an open question whether it should be possible to disable this feature, so that platform classes are _not_ linked.
Changeset: 1e8e543b Author: Hannes Walln��fer <hannesw@openjdk.org> Date: 2020-10-07 13:08:34 +0000 URL: https://git.openjdk.java.net/jdk/commit/1e8e543b

New options should use the double-dash multi-word form. See the JEP for guidelines for command line options. Singular or plural should be decided by the plurality of what is being disabled, not by precedent of existing options.

I have the basic functionality implemented and now I'm thinking about what options we need to make this feature customizable. An obvious option is to disable links to platform API docs. This could be done by an option called `--no-platform-link`. (I was going to use plural form but noticed that all the existing -no* options use singular so I guess that's deliberate.) Regarding using an alternative URL for the platform documentation, being able to provide a property file with a URL for each release feels a bit overkill to me. An invocation of javadoc is usually aware of the JDK release being used (e.g. using the --release or --source options) so it feels more natural to just specify the platform documentation URL directly in the options, e.g. `--link-platform <URL>`.

Although the default should probably be to link to the docs on docs.oracle.com, it would be good to be able to override that from the command line, perhaps by providing a property file with a URL for each supported release.

There are a couple of things that are now maintained inside the maven-javadoc-plugin: the already mentioned URLs per release, but also the package-list/element-list per release (https://github.com/apache/maven-javadoc-plugin/tree/master/src/main/resources/org/apache/maven/plugins/javadoc)