JEP 221：新的 Doclet API
概括
提供Doclet API的替代品以利用适当的 Java SE 和 JDK API，并更新标准 doclet 以使用新的 API。
笔记
在本文档中，术语“旧 Doclet API”指的是 中的 API com.sun.javadoc，“旧标准 doclet”指的是com.sun.tools.doclets.standard.Standard.
术语“新 Doclet API”是指 中的 API jdk.javadoc.doclet，“新标准 doclet”是指 中的API 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 为分析文档注释的内容提供了最少、低效且不完全指定的支持。这给任何想要处理注释内容的 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（当前受支持的 API）已被弃用，并且可能会在将来的版本中删除。鼓励旧 Doclet API 的用户迁移其代码以使用新的 Doclet API。
众所周知，有一些现有的用户编写的 doclet 直接引用旧的“标准 doclet”中的代码，即使该代码不是（也从来不是）受支持的接口。由于该代码难以维护和更新，尤其是最近的新语言功能，因此旧的“标准 doclet”已在 JDK 9 中被弃用并删除，并将在未来版本中删除。
测试
Doclet API 和标准 doclet 的现有测试集已进行调整，以测试新 API 和新标准 doclet。添加了额外的测试来覆盖边缘情况。