Bug ID: JDK-8191363 Add module support for javadoc -link and -linkoffline options

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

Priority: P2
Status: Closed
Resolution: Approved
Fix Versions: 10

Submitted: 2017-11-15
Updated: 2017-12-09
Resolved: 2017-12-08

Summary
-------

Extend the javadoc `-link` and `-linkoffline` options to support references to other modules in external documentation.

Problem
-------

The javadoc `link` and `linkoffline` options take an argument which provides the location of a file which is used when generating links to external documentation. The file is currently called `package-list` and currently just contains a list of packages. This functionality should be generalized to support references to modules in external documentation.

Solution
--------

A new file named `element-list` will be introduced, which will list either just packages, or modules and packages, depending on the documentation with which it is associated. The old name and format will be supported, for now, as an alternative when the new file is not found.

While the file will continue to be a simple text file, the exact form of the file contents is not specified. Such files are generated by javadoc as part of the documentation for an API, and subsequently read by javadoc, to generate references to that API.

Specification
-------------

`-link extdocURL`

where:

- `extdocURL` is a URL for the root directory of some external javadoc-generated documentation, which should contain either a `element-list` or `package-list` file

`-linkoffline extdocURL elementlistLoc`

where

- `extdocURL` is a URL for the root directory of some external javadoc-generated documentation
- `elementlistLoc` is the path or URL to a local directory containing the `element-list` or a `package-list` file for the external documentation.

Note: these are existing options, and the syntax of these options is unchanged. The change is to behavior of these options, in looking for a new file named `element-list` in preference to a file named `package-list`.

Voting the approve the request after clarification, but if the format isn't at least documented for internal purposes, please file a follow-up bug to do so.
08-12-2017
One might reasonably ask, why is a CSR required here? The syntax and arg values for these options will not change. (The arg values point to the enclosing folder, either local or remote) and do not include the filename "package-list". Further, it should not be necessary for users to know about the internal format of the new file, and we should not encourage anyone to manipulate that file directly. The main reason for the CSR is because the previous behavior (with package-list) has been documented, and we are changing that behavior. Further, it is reasonable for people to know about the existence of the new file, as part of the mechanism used to link to modules in other doc bundles.
16-11-2017
Generally, -link and -linkoffline are command-line options that are used when you want to generate a docs bundle that has references to a separate docs bundle. We "never" use these options in the JDK docs because our docs don't depend on other docs. But anyone else publishing an API library with docs, may wish to have clickable links to other types in other libraries, even if only Object, String, List, Map, etc. To set up such links, the standard doclet needs to know something about the content of a docs bundle, and so whenever a docs bundle is generated, the standard doclet writes a file, currently called package-list, listing the packages in that bundle. Then subsequently, when the -link or -linkoffline options are used, another instance of javadoc will read that file to determine whether or not it can create clickable links for references to those packages, or whether to just write plain text names. The options go back a long time and (obviously) predate modules, and need to be updated to support modules. Putting module-related info in a file called "package-list" and changing the format at the same time seems like too big a change, so the proposal is to introduce a new file and format for the info, while retaining legacy support for the old file and format, when the docs being referenced are "non-modular". The file format needs to be written down, sure, but because the file should be a black box to any user of the standard doclet, it does not seem appropriate to specify the file format here. It is an internal format, that should only be written and subsequently read by the standard doclet. We may choose to revisit that decision, and it is indeed regrettably the case that the format of the existing file is documented in the Tool Reference Guide for javadoc on docs.oracle.com. (Sigh.)
16-11-2017
From the description, I'm don't quite understand the intended use of the expanded options. Also, the note that "the exact form of the file contents is not specified" seems problematic. Pending the request.
16-11-2017