JEP 221：新的 Doclet API
概述
提供一个 Doclet API 的替代方案，以利用合适的 Java SE 和 JDK API，并更新标准 doclet 以使用新的 API。
注意
在本文档中，术语“旧 Doclet API”指的是 com.sun.javadoc 中的 API，而“旧标准 doclet”指的是 com.sun.tools.doclets.standard.Standard。
术语“new Doclet API”指的是 jdk.javadoc.doclet 中的 API，而“new standard doclet”指的是 jdk.javadoc.doclet.StandardDoclet。
目标
-
减少过时 API 的维护负担。
-
消除对自定义语言模型 API 的使用，转而采用 Java SE 6 中引入的 标准语言模型 API，即
javax.lang.model。 -
消除对分析文档注释的简化支持，转而采用 JDK 8 中引入的 编译器树 API，即
com.sun.source.doctree。 -
使用合适的新型接口类型替换“模板类”
com.sun.javadoc.Doclet。
非目标
虽然提升性能并非目标，但预计 javadoc 工具和新的标准 doclet 的性能将会因为这项工作而得到改善。
动机
旧的 Doclet API 存在以下需要解决的问题。
-
API 指定一个文档工具（doclet）只是一个实现了部分或全部静态方法的类，正如模板类
com.sun.javadoc.Doclet所示。使用静态方法尤其麻烦，因为它们需要使用静态成员在方法之间共享数据。这对并发使用和测试都有负面影响。 -
API 提供了其自己的语言模型 API，该模型有许多限制（例如，数组没有很好地建模），并且随着 Java 语言在影响 API 签名方面的发展（例如，泛型、类型注解和默认方法），更新负担沉重。
-
API 对分析文档注释内容的支持最少、效率低下且规范不完整。这给任何希望处理注释内容的文档工具带来了重大负担。API 还不支持确定注释中结构在包含源文件中的位置。这使得实际上无法为应报告的任何诊断提供准确的位置信息。旧标准文档工具中对分析注释的支持依赖于一个糟糕且低效的实现，该实现严重依赖子字符串匹配来分离注释中的结构。
描述
新的 Doclet API 在 jdk.javadoc.doclet 包中声明。它使用了语言模型 API 和编译器树 API。
javadoc 工具已更新，以识别针对新 Doclet API 编写的 doclet。旧的 Doclet API 将在过渡期间得到支持，但会被冻结，也就是说，在过渡期间不会更新以支持任何新引入的语言特性。
现有的标准 doclet 支持一个称为 Taglet API 的二级插件 API。Taglet 提供了用户定义自定义标签的能力，这些标签可以在文档注释中使用，并指定这些标签在生成的文档中应该如何显示。更新后的标准 doclet 支持更新的 taglet API。
风险与假设
此外，目前已提供支持的旧 Doclet API 已被弃用，可能会在未来的版本中删除。鼓励旧 Doclet API 的用户迁移其代码以使用新的 Doclet API。
众所周知，目前已有一些现有的用户编写的 doclet 直接引用了旧“标准 doclet”中的代码，尽管该代码从来不是一个受支持的接口。由于该代码难以维护和更新，特别是对于最近的新语言特性而言，旧的“标准 doclet”在 JDK 9 中已被弃用，并将在未来的版本中被移除。
测试
现有的 Doclet API 和标准 doclet 测试集已被调整为用于测试新 API 和新的标准 doclet。还增加了额外的测试以覆盖边缘情况。