JEP 299: Reorganize Documentation | 重新组织文档
摘要
更新 JDK 中文件的组织结构,包括源代码库和生成的文档。
目标
- 正式定义生成的“文档”图像的组织结构,包括 API 规范,“man 页面”(可以视为工具的规范)和其他 JDK 规范。
- 将当前由 javadoc 工具生成的 20 多个文档集合并为 JDK 图像的单个 API 规范集合。
- 定义非 API 规范的组织方式,以便它们可以随源代码一起更新,并且可以轻松地包含在生成的“文档”图像中。
非目标
- 不是目标(反目标)改变任何更新任何规范的程序或流程。这包括 JCP 规范,例如 API 规范和相关标准。
- 不是目标在此工作中包含所有规范。例如,JLS 和 JVMS 不包含在此提案中。
- 不是目标支持不是规范的文档。
- 尽管定义一个可以容纳 man 页面的组织结构是一个目标,但不是为 JDK 9 提供 man 页面的目标。
动机
当前,JDK“文档”目标的标准构建在 20 次(Linux 上为 22 次,Solaris 上为 25 次)上运行 javadoc 工具,以生成相应数量的未组织明显的不同文档集合。即使 javadoc 文档现在提供“搜索”功能,拥有多个文档集合意味着您不能轻松地同时搜索所有提供的文档。
以下是当前文档集合的列表; 每个条目对应于 javac 工具的单独调用。第一个条目(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
的不一致使用都使得难以确定存在哪些文档集合,以及相关规范之间的相对路径应该是什么。当前,这些页面的唯一“索引”隐含在所谓的“brick wall”图像中。
显然,显著减少不同的文档集合并以明确定义的方式组织它们会很好,这样就可以合理地在文档集合之间创建链接。
目前,javadoc 工具生成的各种运行方式由文件 make/common/CORE_PKGS.gmk
和 make/common/NON_CORE_PKGS.gmk
中的逻辑控制。更新这些文件容易出错,有时会被忽略。例如,当前有四个受支持的包未包含在任何公共文档中。最好自动从正在记录文档的模块列表中派生要记录的软件包列表。这意味着每当将新软件包列为从模块导出的软件包时,它都将自动包括在包含模块文档的任何文档中。
此外,OpenJDK 不提供工具的“man 页面”,即使可以将其视为工具命令行的规范。最好将这些规范合并到存储库中,以便在需要时可以与相应的工具一起更新,并且可以在整个文档捆绑包中以定义明确的方式生成和放置相应页面。同样可以说对于各种其他规范,例如 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
目录应包含封闭模块中工具的 man 页面源。这样的文件应使用 Markdown 语法,并且以相应工具的名称命名。例如,javac 工具的 man 页面源应在 src/jdk.compiler/share/man/javac.md
中。
构建系统应在生成的 docs
目录中的一个新的顶级目录中生成相应的文件。生成的文件可以是 HTML 格式,也可以是对于支持该格式的系统而言的“man”格式。例如,javac 工具的生成的 man 页面可以位于
docs/man/javac.html
docs/man/man1/javac.1
其他规范
某些模块可能具有一些其他关联规范,否则不包括在 API 规范或 man 页面中。例如,文档注释通常根据“Javadoc 标签规范”编写,应与更新 javadoc 工具一起更新。(它当前在 Javac 工具指南中可用,位于稍微不太容易记住的网址 [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,因为它支持与辅助功能相关的功能。
Markdown 文件应采用以下格式之一:Markdown;CommonMark;或 GitHub Flavored Markdown,后者提供了对定义列表、表格和代码块的语法高亮等有用扩展。
工具
建议使用开源工具 pandoc 将 Markdown 文件转换为 HTML 或 man 页面(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>