Summary

Add options to disable and customize the linking behaviour to platform classes in Javadoc generated documentation.

Problem

With the introduction of automatic links to Java platform classes arises the need to control or customize this behaviour. People may want to disable linking to platform classes, or generate links directed at some other location.

Solution

Introduce two new options to disable linking to platform classes and to change the target of the generated links.

Specification

The following two options will be added:

 --no-platform-links
      Do not generate links to the platform documentation

The --no-platform-links option causes Javadoc to not generate Java platform links. The output is the same as before the addition of the platform link feature.

--link-platform-properties <url>
      Link to platform documentation URLs declared in properties file at <url>

The --link-platform-properties option causes Javadoc to generate Java platform links using the URLs defined in a properties file at <url>. The properties file must contain entries with the following format, where <release> is the numeric feature release and <URL> is the base URL of the API documentation for that release:

doclet.platform.docs.<release>=<URL>

For example, a properties file with the content listed below causes Javadoc to generate platform documentation links to https://some.domain/docs/<N>/api/ with <N> being the major feature release of the current Javadoc execution and 7 <= N <= 16.

doclet.platform.docs.7= https:/example.com/docs/7/api/
doclet.platform.docs.8= https://example.com/docs/8/api/
doclet.platform.docs.9= https://example.com/docs/9/api/
doclet.platform.docs.10=https:/example.com/docs/10/api/
doclet.platform.docs.11=https://example.com/docs/11/api/
doclet.platform.docs.12=https://example.com/docs/12/api/
doclet.platform.docs.13=https://example.com/docs/13/api/
doclet.platform.docs.14=https://example.com/docs/14/api/
doclet.platform.docs.15=https://example.com/docs/15/api/
doclet.platform.docs.16=https://example.com/docs/16/api/

If the argument passed to the --link-platform-properties option does not specify a URL scheme the argument is interpreted as file path.

If the properties file passed as argument to the --link-platform-properties option cannot be read javadoc exits with an error. If the properties can be read but does not contain an entry for the current release no error is raised, but no platform links are generated.