JEP 299：重新组织文档

概括

更新 JDK 中源存储库和生成的文档中文档的组织。

目标

正式定义生成的“文档”映像的组织，包括 API 规范、“手册页”（可以认为是工具规范）和其他 JDK 规范。
将 javadoc 工具生成的当前 20 多组文档合并为 JDK 映像的 API 规范的单个集合。
定义要出现在源存储库中的非 API 规范的组织，以便它们可以根据需要与源代码一起更新，并且可以轻松包含在生成的“文档”映像中。

非目标

改变决定更新任何规范的任何流程或程序不是目标（而是反目标）。这包括 JCP 规范，例如 API 规范和相关标准。
这项工作的目标并不是包含所有规范。例如，JLS和JVMS不包括在该提案中。
支持非规范的文档并不是目标。
尽管定义一个可以容纳手册页的组织是一个目标，但提供 JDK 9 的手册页并不是目标。

动机

目前，JDK“docs”目标的标准构建运行 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，都使得很难确定存在哪些文档集，以及相关规范之间的相对路径应该是什么。目前，这些页面的唯一“索引”隐含在所谓的“砖墙”图片中。

最好显着减少不同文档集的数量，并以明确定义的方式组织它们，以便在文档集之间和文档集内创建链接是合理的。

make/common/CORE_PKGS.gmkjavadoc 工具的这些不同运行当前由文件和中的逻辑控制make/common/NON_CORE_PKGS.gmk。更新这些文件很容易出错，有时甚至会被忽视。例如，当前有四个受支持的软件包未包含在任何公共文档中。最好从正在记录的模块导出的包列表中自动派生出要记录的包列表。这意味着每当一个新包被列为从模块导出时，它都会自动包含在包含该模块文档的任何文档中。

此外，OpenJDK 并不为其提供的工具提供“手册页”，尽管它们可以被视为工具命令行的规范。最好将这些规范合并到存储库中，以便在必要时可以与相应的工具一起更新它们，并生成相应的页面并以明确定义的方式放置在整个文档包中。同样的情况也适用于各种附加规范，例如 JNI 规范或 Javadoc 标签规范，这些规范目前没有明确定义的归属。

最后，当前的文档包实际上是“全有或全无”。如果我们在存储库中组织任何文档，使其可以与其应用的模块相关联，那么我们将能够构建包含特定图像子集的图像以及相应的文档。例如，如果我们为不同的Compact Profiles构建镜像，我们可以轻松构建并发布相应的文档。

描述

综合 API 文档

生成的 API 文档的整合需要对 makefile 进行更改，以便我们识别包含要记录的 API 的模块，并生成包含所有这些模块的捆绑包，应记录其所有导出的 API。如果这没有涵盖当前生成的所有 API 文档，我们应该定义其他文档集的组织。例如，定义各个集合作为同级存在于单个顶级“api”目录中。

docs/api/<doc-set>/

<doc-set>应该是描述相应内容的通用名称，例如“jdk”或“java.se”。

“手册页”

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 Tag 规范”编写的，该规范应与 javadoc 工具的更新一起更新。（目前可以在《Javac 工具指南》中找到，网址有点难以记住 [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDFCBAD\]）

以下是一些可以考虑纳入的附加规范：

此类规范应放置在另一个新的特定于模块的目录中：

src/<module-name>/{share,<os-name>}/specs

此类目录中的文件应复制到specs生成docs目录中的目录中，但 Markdown ( ) 文件除外.md，应将其转换为 HTML 文件。如果规范包含多个文件，建议将所有文件分组到适当的子目录中。

指数

构建应该生成一个简单的最小顶级index.html文件，该文件链接到整个生成的文档中的每个项目。这对于基本“文档”构建中的简单导航来说应该足够了，但在提供更丰富的文档包时可能会根据需要被覆盖。

格式

HTML 文件应采用 HTML 5 或 HTML 4.01 格式，并且应通过验证器，例如tidy、链接检查器和可访问性检查器。随着时间的推移，我们应该将所有旧的 HTML 文件迁移到 HTML 5，因为它支持与辅助功能相关的功能。

Markdown 文件应采用以下格式之一：Markdown；通用标记；或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>

JEP 299：重新组织文档

概括​

目标​

非目标​

动机​

描述​

综合 API 文档​

“手册页”​

附加规格​

指数​

格式​

工具​

概括​

概括

目标

非目标

动机

描述

综合 API 文档

“手册页”

附加规格

指数

格式

工具

概括