跳到主要内容

JEP 172：DocLint

QWen Max 中英对照

概述​

提供一种方法，用于在开发周期的早期检测 Javadoc 注释中的错误，并且能够轻松链接回源代码。

目标​

javadoc 工具目前对 Javadoc 注释的内容检查很少，甚至不进行检查，而且它所进行的检查也无法与源代码关联，通常会被开发者忽略。因此，错误通常会传播到生成的文档文件中，从而影响这些文件中的规范。我们需要更好的工具来帮助更早地检测出更多错误，以便报告的问题易于修复。

典型错误可以分为多种类型：

  • 语法错误，例如未转义的字符（<）或不匹配的括号（{@foo）
  • 错误的 HTML，例如无效或缺失的标签或属性
  • 错误的引用，例如使用 @see 引用不存在的类型，或使用 @param 引用不存在的参数
  • 可访问性错误，例如表格缺少摘要或标题
  • 信息缺失，例如未记录的参数

其目标是检测并报告开发人员编写 Javadoc 注释时犯的大多数常见错误，以确保生成的输出文件通常能够通过外部验证工具（如 HTML 和无障碍合规性工具）的检查。

任何错误都应以类似于常见编译器的方式报告，以便这些消息可以被合适的编辑器和集成开发环境（IDE）轻松读取，从而帮助开发者轻松定位并修复错误。

用户应该能够配置该工具，以选择或限制所进行的检查。例如，仅报告不良语法的实例，或者仅报告公共和受保护方法上的错误。

非目标​

我们的目标并不是检测所有问题，以确保生成的文档能够通过任何指定的验证工具。

动机​

Java SE 平台的 API 规范主要基于由 javadoc 工具生成的文档。在 API 规范中发现的错误可以追溯到原始 Javadoc 注释中的错误。通过提供工具来及时检测和报告此类错误，我们可以降低发布不正确规范的风险。

此外，通过确保 javadoc 工具的输出符合现行标准，我们降低了它在某些平台和浏览器组合上无法正常工作的风险。

如今，生成的文档通常被认为应遵循无障碍指南（如 Section 508）这一点非常重要。我们需要更好的工具来帮助我们在开发周期中容易修复问题的阶段检测可能存在的错误。

现有的形式化工具，例如 HTML 和无障碍合规性检查器，只能应用于 javadoc 工具的 输出。这使得很难将任何错误消息与原始源文本中的位置关联起来。我们需要能够在原始源代码上下文中报告错误的工具。

描述​

该工具将基于 JEP 105 中描述的 “DocTree API” 构建，而 DocTree API 本身是 javac “Tree API” 的一个扩展，现在位于 com.sun.source 包中。DocTree API 提供了一种获取 Javadoc 注释元素的 “语法树” 的方法。

该工具将扫描源文件，寻找具有关联 Javadoc 注释的声明。它将使用 DocTree API 来解析这些注释，然后分析生成的 AST 以查找问题。

该工具可以通过多种方式提供。

  1. 由于它正在处理 Javadoc 注释，因此展示该工具的自然方式可以是作为一个 doclet。用户会在 javadoc 命令行中指定使用 doclet，利用现有的 javadoc 的 -doclet 和 -docletpath 选项。该 doclet 将提供额外的选项来选择要报告的问题类别，方式类似于现有的 javac -Xlint 选项。

    这个选项的一个变体是将该工具“硬编码”到现有的标准 doclet 中。这为用户调用该工具提供了更简单的方法，但确实意味着会有性能损失，因为标准 doclet 尚未利用 DocTree API。（这将是另一个项目值得称赞的目标。）然而，javadoc 已经很慢（！！），而使用 DocTree API 解析注释很快，所以感知到的减速可能不会太麻烦。

    无论哪种方式，使用 javadoc 工具生成文档通常是在工具链后期才会考虑的事情。许多开发人员甚至不运行该工具，因此这样的解决方案无法满足及时报告问题的目标。

  2. 该工具可以作为一个全新的独立工具提供。这意味着需要额外的工作，例如提供启动器和相关的手册页。早期使用 apt 注解处理工具的经验表明，将一个新工具引入典型的开发者工具链是很困难的。

  3. 该工具可以“集成到”javac 中，这样开发人员可以选择在查看源代码问题消息的同时查看 Javadoc 注释中的问题消息。这意味着启用该工具可以像在 javac 命令行中添加另一个选项一样简单。由于该工具将支持自己的配置选项，因此使用该工具并不是可以添加到现有 javac -Xlint 机制中的二元选择。相反，建议该工具使用一个类似但不同的选项，即 -Xdoclint 或 -Xdoclint:args。

  4. 该工具还可以集成到像 NetBeans 这样的 IDE 中，NetBeans 已经使用了 javac 的一种变体来在源代码编辑器窗口中提供错误反馈。修改 NetBeans 源代码编辑器超出了范围，但该工具不应妨碍其他人将其集成到 IDE 中，以便我们不仅在 Javadoc 注释中有拼写错误时获得“红色波浪线”。

预计我们将结合选项 1 和选项 3，通过 javac 和 javadoc 提供该工具。

替代方案​

确保 javadoc 工具生成有效的 HTML 输出的问题，可以通过使用类似 htmltidy 的工具对输出进行半自动后处理来解决。然而，从无效输入生成“干净”的 HTML 只是掩盖了问题，并无助于解决查找（和修复）原始源文本中错误的根本问题。

测试​

我们应该继续运行可用的正式验证工具，对从 OpenJDK 源代码生成的文档进行检查。然后，我们需要确认这些工具报告的任何错误也能被新工具检测到并报告。

风险与假设​

如果该特性将被包含在 JDK 8 中，主要风险是资源的可用性。缓解计划是暂时将该工具单独提供，以便在平台的后续版本中再进行集成。

依赖​

取决于 JEP 105，该功能现已在 JDK 8 build 66 (M5) 中提供。

影响​

  • 可访问性：将有助于提高我们生成的文档的可访问性。
  • 文档：将有助于提高我们生成的文档对 HTML 标准的符合性。