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.

A better organization would be to have a top-level directory per module, and to create the package-hierarchy for the types in the module as a directory tree under the top-level module directory. Module-specific files, like the module summary page then become <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 accomodate the module-oriented layout.