JDK-8191776 : Update javadoc Tool Reference Guide with details
  • Type: Sub-task
  • Component: docs
  • Sub-Component: guides
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2017-11-22
  • Updated: 2018-03-05
  • Resolved: 2018-03-05
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 10
10Fixed
Description
Make sure the Tool Reference guide for javadoc explains the difference between -link and -linkoffline, and when to prefer -linkoffline over -link.
Comments
Generally, JDK-8164407 (Add module support for -link and -linkoffline javadoc options) enhances the -link and -linkoffline options to work with modules. As a result, existing docs about these options is now somewhat outdated, in that it is now incomplete. Previously, the description for these options referred to a file called "package-list". That file still exists and is still used when the javadoc tool is just being used to document packages. The file lists the packages available in an API. But if the tool is being used to generate API docs for modules, a new/different file is used, called "element-list". This new file lists both modules and packages available in an API. To some extent both of these files are a bit "under the covers", in that the user does not have to manipulate these files directly. But to the extent that they are documented, the documentation should be correct and up to date.
03-01-2018
Hi [~jjg], can you please clarify what change is needed? The existing documentation for javadoc in the Tools Ref at https://docs.oracle.com/javase/9/tools/javadoc.htm#GUID-9D532574-1CDB-4D30-99F3-A308DCAEE55F__STANDARDDOCLETOPTIONS-9A14BD97 already contains information about both -link and -linkoffline. Is that incorrect, or is more needed?
13-12-2017