JDK 8 中的 Javadoc：“不允许自动关闭元素”无效

Posted 2023-03-30

【中文标题】JDK 8 中的 Javadoc：“不允许自动关闭元素”无效

【英文标题】：Javadoc in JDK 8 : Invalid "self-closing element not allowed"

【发布时间】：2014-11-20 20:39:46

【问题描述】：

使用 JDK 8 运行 javadoc 并收到此错误时，最好的解决方法是什么。

似乎对于 JDK 8，已经决定像 <br /> 和 <p /> 这样的标签应该产生错误，因为它们是无效的（严格的）html 4。see discussion JDK mailing list here

我想知道，因为我只是想使用 maven 编译一些 java 项目并被这个问题绊倒。当然，我可以向项目提交票证（我想我会的），但如果有办法禁用这种行为（对于机器），那就太好了。否则，我预计需要修复很多项目才能在 JDK 8 上毫无问题地构建它们。

【问题讨论】：

-Xdoclint:none 有效吗？

谷歌搜索这个选项产生了一个非常好的链接：blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

JDK8 and Javadoc has become very strict的可能重复

链接文章中的原因与触发此问题的原因不同。

相关。从 maven 获取相同的错误类型：***.com/questions/15886209/…

【参考方案1】：

对于这两种特殊情况，我认为建议的操作是将它们替换为<p>。 This 是 Oracle 文档的链接。

【讨论】：

最佳建议来自@JE42 使用此blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html 设置blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

【参考方案2】：

要删除 javaDocs 中的错误，只需替换：

<p/> 只需 <p> <br/> 只需 <br>

在以例外方式更正后一切正常。

【讨论】：

简单地将

【参考方案3】：

取自 oracle.com 的“What's New in JDK 8”：

javac 工具现在支持在运行 javadoc 时生成的文件中检查 javadoc cmets 的内容是否存在可能导致各种问题的问题，例如无效的 HTML 或可访问性问题。该功能由新的 -Xdoclint 选项启用。有关更多详细信息，请参阅运行“javac -X”的输出。此功能在 javadoc 工具中也可用，并且默认启用。

现在我按照它告诉我的去做了。在 JDK 7 上，“javac -X”的输出没有提到 -Xdoclint 选项。但是，在 JDK 8 上，它给出了：

 -Xdoclint:(all|none|[-]<group>)[/<access>]
    Enable or disable specific checks for problems in javadoc comments,
    where <group> is one of accessibility, html, missing, reference, or syntax,
    and <access> is one of public, protected, package, or private.

因此，按如下方式运行 Javadoc 实用程序：

javadoc.exe -Xdoclint:none <other options...>

在我的脚本中，您提到的错误通过使用此选项消失了。

【讨论】：

是的，没错。但是，JDK 7 的 javdoc 将无法使用此选项，这意味着您必须检测对新选项的支持。最后，我最终修复了 html。

如果项目使用 maven，您可以使用仅为 jdk8 激活的配置文件。如果可以的话，最好只修复 HTML 并在项目中提交错误。

【参考方案4】：

虽然可以使用 -Xdoclint 选项禁用错误检查，但它不能修复问题，它只是隐藏了问题。要制作有效的 HTML4 文档，以下替换是正确的。

用常规的 br 标记替换自闭 br 标记（ 用 ） 用br标签替换空的p标签（

用） 确保所有 p 标签都有内容并关闭（

... 与

...

）