JEP 221: New Doclet API | 简化的 Doclet API
摘要
提供一个替代Doclet API的解决方案，以利用适当的 Java SE 和 JDK API，并更新标准 doclet 以使用新 API。
注意
在本文档中，“旧的 Doclet API”一词指的是com.sun.javadoc中的 API，而“旧的标准 doclet”指的是com.sun.tools.doclets.standard.Standard。
术语“新的 Doclet API”指的是jdk.javadoc.doclet中的 API，而“新的标准 doclet”指的是jdk.javadoc.doclet.StandardDoclet。
目标
- 减少过时 API 的维护负担。
- 使用 Java SE 6 中引入的标准语言模型 API，
javax.lang.model，取代自定义语言模型 API 的使用。 - 放弃对文档注释的简单分析支持，转而使用 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 还不支持确定注释中构造的源文件中的位置，因此无法为应报告的任何诊断提供准确的位置信息。分析注释的支持由旧的标准 doclet 中的一个差劲而低效的实现支持，该实现在在注释中使用子字符串匹配来分隔构造。
说明
新的 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。还新增了覆盖边缘案例的其他测试。