JEP 299：重组文档
概述
更新 JDK 中源代码存储库和生成的文档中的文档组织结构。
目标
- 正式为生成的“文档”镜像定义一个组织结构，以包含 API 规范、“手册页”（可视为工具的规范）以及其他 JDK 规范。
- 将当前由 javadoc 工具生成的 20 多套文档整合为一个 JDK 镜像的 API 规范集合。
- 为源代码仓库中存在的非 API 规范定义一个组织结构，以便它们可以随着源代码的更新而进行必要的修改，并能够轻松地包含在生成的“文档”镜像中。
非目标
- 更改决定更新任何规范（包括 JCP 规范，如 API 规范和相关标准）的任何流程或程序不是目标（而是反目标）。
- 此工作不包含所有规范。例如，JLS 和 JVMS 不在此提案中。
- 支持非规范的文档不是目标。
- 尽管定义一个可以容纳 man 页面的组织是一个目标，但为 JDK 9 提供 man 页面并不是目标。
动机
目前，JDK “文档”目标的标准构建会运行 javadoc 工具 20 多次（在 Linux 上是 22 次，在 Solaris 上是 25 次），以生成相应数量的不同文档集，而这些文档集的组织方式并不明显。尽管 javadoc 文档现在提供了一个“搜索”功能，但拥有多套文档意味着您无法轻松一次性搜索所有提供的文档。
以下是当前文档集的列表；每个条目对应于对 javadoc 工具的一次单独调用。第一个条目（api）是大多数人所熟悉的：它是 Java SE 平台规范。
api
jdk/api/attach/spec
jdk/api/dynalink
jdk/api/javac/tree
jdk/api/javadoc/doclet
jdk/api/javadoc/old/doclet
jdk/api/javadoc/old/taglet
jdk/api/jconsole/spec
jdk/api/jlink
jdk/api/jpda/jdi
jdk/api/jshell
jdk/api/nashorn
jre/api/accessibility/jaccess/spec
jre/api/management/extension
jre/api/net/httpserver/spec
jre/api/net/socketoptions/spec
jre/api/nio/sctp/spec
jre/api/plugin/dom
jre/api/plugin/jsobject
jre/api/security/jaas/spec
jre/api/security/jgss/spec
jre/api/security/smartcardio/spec
虽然有一个表面上的总体组织结构，但不同的深度、api 组件位置的不同、spec 使用的不一致，都使得确定存在哪些文档集以及相关规范之间的相对路径应该是什么变得困难。目前，这些页面唯一的“索引”隐含在所谓的“砖墙”图中。
显著减少不同文档集的数量，并以明确的方式对它们进行组织，这样可以合理地在文档集之间以及文档集内部创建链接，这样做会很有好处。
当前，这些 javadoc 工具的各种运行由 make/common/CORE_PKGS.gmk 和 make/common/NON_CORE_PKGS.gmk 文件中的逻辑控制。更新这些文件容易出错，而且有时会被忽略。例如，目前有四个受支持的包未包含在任何公共文档中。最好是从被记录模块导出的包列表中自动生成需要记录的包列表。这意味着，每当一个新包被列为从某个模块导出时，它将自动包含在包括该模块文档在内的任何文档中。
此外，OpenJDK 并未为其提供的工具提供“手册页 (man pages)”，尽管这些可以被视为工具命令行的规范。将此类规范整合到代码库中将会很有帮助，这样在必要时它们可以与相应的工具一同更新，并生成对应的页面，以一种明确定义的方式放置在整体文档集合中。对于各种其他规范也是如此，例如 JNI 规范或 Javadoc 标签规范，这些目前都没有一个明确的归宿。
最后，当前的文档包实际上是“全有或全无”的形式。如果我们在存储库中组织任何文档，使其可以与适用的模块相关联，那么我们就能够构建包含特定图像子集以及相应文档的图像。例如，如果我们为不同的 Compact Profiles 构建镜像，就可以轻松地构建并发布相应的文档。
描述
统一的 API 文档
整合生成的 API 文档需要对 makefile 进行修改，以便我们识别包含要记录 API 的模块，并生成一个包含所有这些模块的捆绑包，这些模块的所有导出 API 都应被记录。如果这并未涵盖当前生成的所有 API 文档，我们应该定义额外文档集的组织方式。例如，可以定义各个文档集作为单个顶级 “api” 目录中的同级存在。
docs/api/<doc-set>/
<doc-set> 应为描述相应内容的通用名称，例如 "jdk" 或 "java.se"。
“Man 页面”
JDK 仓库中的源代码通常按以下方式组织：
src/<module-name>/{share,<os-name>}/{classes,native,...}
建议用一个新变体扩展最后一个此类组件：
src/<module-name>/{share,<os-name>}/man
man 目录应包含外围模块中工具的手册页源文件。此类文件应使用 Markdown 语法，并以相应的工具命名。例如，javac 工具的手册页源文件应位于 src/jdk.compiler/share/man/javac.md 中。
构建系统应该在生成的 docs 目录中的一个新的顶层目录中生成相应的文件。生成的文件可以是 HTML 格式，或者对于支持该格式的系统，也可以是 "man" 格式。例如，javac 工具生成的手册页可以位于：
docs/man/javac.html
docs/man/man1/javac.1
其他规格
一些模块可能具有某些额外的关联规范，这些规范并未包含在 API 规范或手册页中。例如，文档注释通常是根据 Javadoc 标签规范 编写的，该规范应随着 javadoc 工具的更新而更新。（目前它可以在 Javac 工具指南中的不太容易记住的 URL 下找到：[https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDFCBAD\]）
以下是可能会被考虑纳入的一些额外规格：
此类规范应置于另一个新的模块特定目录中：
src/<module-name>/{share,<os-name>}/specs
此类目录中的文件应复制到生成的 docs 目录中的 specs 目录，但 Markdown（.md）文件除外，这些文件应转换为 HTML 文件。如果一个规范由多个文件组成，建议将所有文件分组到一个适当的子目录中。
索引
构建过程应生成一个简单的顶级 index.html 文件，该文件链接到整体生成文档中的每个项目。这应该足以满足基本 “docs” 构建中的简单导航，但在提供更丰富的文档包时，可以根据需要覆盖此文件。
格式
HTML 文件应为 HTML 5 或 HTML 4.01 格式，并且应通过诸如 tidy、链接检查器和可访问性检查器等验证工具。随着时间的推移，我们应该将所有旧的 HTML 文件迁移到 HTML 5，因为 HTML 5 支持与可访问性相关的功能。
Markdown 文件应为以下格式之一：Markdown；CommonMark；或 Github Flavored Markdown，后者为定义列表、表格和代码块的语法高亮提供了有用的扩展功能。
工具
我们建议使用开源的 pandoc 工具将 Markdown 文件转换为 HTML 或 man page（groff）格式。这意味着构建过程会增加一些新的工具依赖。pandoc 支持上一节中列出的所有 Markdown 变体。
概述
新源子目录：
src/<module-name/{share,<os-name>}/
man
specs
新生成的文档目录：
docs/
api/
<doc-set-1>
<doc-set-2>
etc
man/
<HTML man pages>
man1/
<man pages in man format>
specs/
<HTML spec pages>
<directories for multi-file specifications>