JEP 172: DocLint
摘要
提供一种在开发周期的早期阶段检测 Javadoc 注释中错误的方法，并且可以轻松地将其与源代码关联起来。
目标
当前的 javadoc 工具在 Javadoc 注释的内容检查方面提供的功能很少或者几乎没有，并且提供的检查结果不能与源代码关联起来，通常被开发人员忽视。结果就是错误通常会传播到生成的文档文件中，影响这些文件中的规范。我们需要更好的工具来帮助检测更多的错误，并且尽早发现这些问题，以便报告的问题易于修复。
常见的错误可以分为不同的类别：
- 语法错误，例如未转义的字符（
"<"）或不匹配的括号（"{@foo"） - 错误的 HTML，例如无效或缺少的标签或属性
- 错误的引用，例如使用
@see引用不存在的类型，或使用@param引用不存在的参数 - 可访问性错误，例如表格中缺少摘要或标题
- 丢失的信息，例如未记录的参数
目标是检测和报告开发人员编写的 Javadoc 注释中的大多数常见错误，以便生成的输出文件通常可以通过外部验证工具（例如 HTML 和可访问性符合性工具）通过。
任何错误都应该以类似于常见编译器的方式报告，以便适合的编辑器和 IDE 轻松消化这些消息，以帮助开发人员轻松定位和修复错误。
用户应该能够配置工具以选择或限制进行的检查。例如，仅报告语法错误的情况，或仅在公共和受保护的方法上报告错误。
非目标
目标不是检测所有问题，以便我们可以保证生成的文档将通过任何指定的验证工具。
动机
Java SE 平台的 API 规范主要基于 javadoc 工具生成的文档。已经发现了 API 规范中的错误，这些错误可以追溯到原始 Javadoc 注释中的错误。通过及时提供检测和报告此类错误的工具，我们可以降低发布不正确规范的风险。
此外，通过确保 javadoc 工具的输出符合现行标准，我们可以减少其在某些平台和浏览器组合上不起作用的风险。
如今，让生成的文档符合可访问性指南（如 Section 508）被普遍认为很重要。我们需要更好的工具，在开发周期的某个时点帮助检测可能的错误，以便容易修复此类问题。
现有的形式化工具（如 HTML 和可访问性符合性检查器）只能应用于 javadoc 工具的输出结果。这使得很难将任何错误消息与原始源文本中的位置联系起来。我们需要能够在原始源的上下文中报告错误的工具。
描述
该工具将建立在 “DocTree API” 之上，该 API 在 JEP 105 中进行了描述，JEP 105 本身是 javac “Tree API” 的扩展，现在已经在 com.sun.source 包中可用。DocTree API 提供了一种获取 Javadoc 注释元素的“语法树”的方法。
该工具将扫描源文件，查找具有关联 Javadoc 注释的声明。它将使用 DocTree API 解析这些注释，然后分析生成的 AST 以查找问题。
该工具可以以多种方式提供。
作为 doclet 提供工具是处理 Javadoc 注释的自然方式。用户可以在
javadoc命令行上使用现有的javadoc-doclet和-docletpath选项指定使用 doclet。doclet 将提供额外的选项来选择要报告的问题类别，类似于现有的javac -Xlint选项。这个选项的变体是将工具硬编码到现有的标准 doclet 中。这样，用户可以更简单地调用工具，但这意味着会有性能损失，因为标准 doclet 尚未使用 DocTree API。然而，
javadoc已经很慢，并且使用 DocTree API 解析注释非常快，因此感知到的减速可能不会太大。无论哪种方式，使用
javadoc工具生成文档通常是在工具链的后期阶段的事后思考。许多开发人员甚至不运行该工具，因此这种解决方案无法及时报告问题的目标。将工具作为新的独立工具提供。这将需要额外的工作，例如提供一个启动器和相关的手册页。以前使用
apt注解处理工具的经验表明，将新工具引入典型的开发人员工具链是困难的。将工具与 javac 集成，使开发人员可以选择同时查看源代码中的 Javadoc 注释问题和源代码中的问题。这意味着启用工具只需在 javac 命令行中添加另一个选项。由于工具将支持自己的配置选项，使用工具不是可以添加到现有的
javac -Xlint机制中的二进制选择。相反，建议工具使用类似但不同的选项，如-Xdoclint或-Xdoclint:args。工具还可以与 NetBeans 等 IDE 集成，NetBeans 已经使用
javac的变体为源编辑器窗口提供有关错误的反馈。修改 NetBeans 源编辑器不在范围内，但该工具不应排除其他人将该工具集成到 IDE 中的可能性，以便我们不仅在 Javadoc 注释中遇到拼写错误时获得“红色波浪线”。
预计我们将对选项 1 和选项 3 进行某种组合，通过 javac 和 javadoc 提供工具。
替代方案
解决 javadoc 工具生成有效 HTML 输出的问题可以通过将输出进行半自动处理（例如使用 htmltidy 等工具）来解决。然而，从无效输入生成“清洁”的 HTML 只是掩盖了问题，没有帮助解决原始源文本中的错误问题。
测试
我们应该继续对从 OpenJDK 源代码生成的文档运行可用的形式化验证工具。然后，我们应该检查这些工具报告的任何错误是否也被新工具检测和报告。
风险和假设
如果要将此功能包含在 JDK 8 中，主要风险是资源的可用性。减轻计划是现在将工具单独提供，以便在以后的平台版本中将其包含进来。
依赖
依赖于JEP 105，它现在可以在 JDK 8 构建 66（M5）中使用。
影响
- 可访问性：将有助于改善生成文档的可访问性
- 文档：将有助于改善生成文档的 HTML 标准符合性。