Summary

When generating API documentation for modules, organize the generated files by module and package, not just by package, and add a temporary option to mitigate any issues that may arise.

Problem

When generating the documentation for a series of modules, the pages for the packages and classes in that module are organized in a "traditional" package hierarchy, without any appearance of the module-name in the file path. In addition, any module-specific files are named in the form <module-name>-<page-kind>.html. This leads to a very cluttered top-level directory, and worse, it allows the possibility of files for one module overwriting some of the files for a different module, in the case when both modules contain a like-named package. While that may be uncommon, it is not disallowed, because javadoc does not have equivalent to the constraints on modules being analyzed by the compiler (javac) and runtime.

Solution

Use a top-level directory per module, placing the package-hierarchy for the types in the module as a directory tree under that top-level module directory. Module-specific files, like the module summary page will likewise be placed in that module-specific directory, using <module-name>/<page-kind>.html instead of <module-name>-<page-kind>.html.

For the most part, this change will be transparent to the authors writing doc-comments, because for the most part, the links are either generated by the doclet itself, to link to other program elements, or the links are generated in response to @see and {@link} tags in the documentation comment, which just abstractly reference program elements, which any details of the file layout. The one other case is when an author writes an explicit <a href=...> in a doc comment. The two reasons to use such links is (1) to reference user-written anchors <a id=...> within the documentation and (2) to reference auxiliary files, such as in doc-files subdirectories. We do not currently support top-level doc-files in a module, because of the issues being presented here. While we could support them in the current layout scheme, it would be better to settle on the preferred layout scheme before we open up the ability to use top-level doc-files in a module. (See JDK-8194553)

Because of the potential to negatively impact user-written <a href=...> links, we should provide a temporary option to have the doclet revert to its current package-oriented behavior. Using such an option should generate a warning, advising authors to update their docs to accommodate the module-oriented layout.

There is a another related but smaller issue, with respect to linking between doc bundles, using the -link and -linkoffline command-line options. Because we expect to eventually only support the new file layout in future, it does not seem worthwhile to provide an interim ability to link to different doc bundles using a mix of the old and new file layout. The primary existing example of multi-module documentation is the JDK API documentation itself. Anyone wishing to have their documentation linked to the JDK documentation will have to update their documentation to use the new file layout.

Specification

All files specific to a module, including summary files as well as all pages for the packages and types declared in that module will be placed under a top-level directory named after the module. All internal links generated by the doclet will be updated accordingly.

A new option, taking no arguments, will be added to suppress the new behavior. The name of the option is --no-module-directories. It is expected that this option will be removed in a future release, when users have had a reasonable opportunity to update any explicit <a href=...> links in their documentation.