JEP 172：DocLint
概括
提供一种在开发周期早期检测 Javadoc 注释中的错误的方法，并且可以轻松链接回源代码。
目标
该javadoc工具目前几乎不提供对 Javadoc 注释内容的检查，并且它提供的检查不会链接回源代码，并且通常会被开发人员忽视。因此，错误通常会传播到生成的文档文件中，这可能会影响这些文件中的规范。我们需要更好的工具来帮助更早地检测更多错误，以便更容易修复报告的问题。
典型错误可分为以下几类：
- 语法错误，例如未转义字符 ("<") 或不匹配的括号 ("{@foo")
- HTML 错误，例如标签或属性无效或缺失
- 错误引用，例如使用 @see 引用不存在的类型，或使用 @param 引用不存在的参数
- 辅助功能错误，例如表格中缺 少摘要或标题
- 缺少信息，例如未记录的参数
目标是检测并报告开发人员在编写 Javadoc 注释时所犯的大多数常见错误，以便生成的输出文件通常能够通过外部验证工具，例如 HTML 和可访问性一致性工具。
任何错误都应该以类似于普通编译器的方式报告，以便合适的编辑器和 IDE 可以轻松使用这些消息，以帮助开发人员轻松定位和修复错误。
用户应该能够配置该工具来选择或限制所做的检查。例如，仅报告错误语法的实例，或仅报告公共和受保护方法的错误。
非目标
检测所有问题并不是我们的目标，这样我们就可以保证生成的文档将通过任何指定的验证工具。
动机
Java SE 平台的 API 规范主要基于该javadoc工具生成的文档。 API 规范中发现的错误可以追溯到原始 Javadoc 注释中的错误。通过提供及时检测和报告此类错误的工具，我们可以降低发布不正确规范的风险。
此外，通过确保该javadoc工具的输出符合现行标准，我们降低了该工具无法在某些平台和浏览器组合上运行的风险。
如今，人们普遍认为生成的文档符合可访问性指南（例如第 508 节）非常重要。我们需要更好的工具来帮助在开发周期中易于修复此类问题的某个时刻检测可能的错误。
现有的正式工具（例如 HTML 和可访问性一致性检查器）只能应用于工具的_输出_javadoc。这使得很难将任何错误消息与原始源文本中的位置 相关联。我们需要能够在原始来源的上下文中报告错误的工具。
描述
该工具将构建在JEP 105中描述的“DocTree API”之上，它本身是包中现在可用的 javac“Tree API”的扩展com.sun.source。 DocTree API 提供了一种获取 Javadoc 注释元素的“语法树”的方法。
该工具将扫描源文件，查找具有关联 Javadoc 注释的声明。它将使用 DocTree API 来解析这些注释，然后分析生成的 AST 来查找问题。
该工具可以通过多种方式提供。
-
由于它正在处理 Javadoc 注释，因此呈现该工具的自然方式可能是作为 doclet。用户可以
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 build 66 (M5) 中可用。
影响
- 可访问性：将有助于提高我们生成的文档的可访问性
- 文档：将有助于提高我们生成的文档对 HTML 标准的一致性。