Bug ID: JDK-8251181 New javadoc options for auto-link to platform classes

Type: CSR
Component: tools
Sub-Component: javadoc(tool)

Priority: P3
Status: Closed
Resolution: Approved
Fix Versions: 16

Submitted: 2020-08-05
Updated: 2020-09-29
Resolved: 2020-09-29

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.

Updated to use example.com and moving to Approved.
29-09-2020
FYI, optional, the domain name `example.com` explicitly exists for use in example cases like this, if you want to use it.
25-09-2020
I renamed the `--no-platform-link` option to `--no-platform-links` (plural) as suggested by Jon.
23-09-2020
I have updated the CSR with more details about the `--link-platform-properties` option, adding an example properties file and adding a sentence saying that if no URL scheme is provided `file:` scheme is assumed.
21-09-2020
Should --link-platform-properties allow a file, or otherwise assume `file:` scheme if no scheme specified in the URL?
18-09-2020
Agreed the man page is the best place to document the format of the properties file, since the man page will also need to updated with the new options. The exact target of the URL should be specified, if necessary by example. For example, is it the "directory/folder", the top-level index.html file, the top-level element-list file, etc. Question: should we document the default locations for supported releases?
18-09-2020
Moving to Provisional. Where is the format of the properties file proposed to be documented; the javadoc man page?
16-09-2020