使用 Maven 时如何绕过更严格的 Java 8 Javadoc

Question

您很快就会意识到 JDK8 在涉及 Javadoc 时要严格得多（默认情况下）。 （ 链接- 请参阅最后一个要点）

如果您从不生成任何 Javadoc，那么您当然不会遇到任何问题，但是诸如 Maven 发布过程和您的 CI 构建之类的事情可能会突然失败，而它们在 JDK7 中工作得很好。现在，任何检查 Javadoc 工具退出值的操作都会失败。与 JDK7 相比，JDK8 Javadoc 在 warnings 方面可能也更冗长，但这不是这里的范围。我们正在谈论 errors ！

这个问题的存在是为了收集关于如何处理它的建议。什么是最好的方法？这些错误是否应该在源代码文件中一劳永逸地修复？如果你有一个庞大的代码库，这可能需要大量的工作。还有哪些其他选择？

也欢迎您评论以前可以通过的现在失败的故事。

现在失败的恐怖故事

wsimport 工具

wsimport 工具是用于创建 Web 服务消费者的代码生成器。它包含在 JDK 中。即使您使用 JDK8 的 wsimport 工具，它仍然会生成 无法使用 JDK8 的 javadoc 编译器编译的 源代码。

@作者标签

我正在打开 3-4 年前的源代码文件，然后看到：

 /**
 * My very best class
 * @author John <[e-mail]>
 */

由于 < 字符，这现在失败了。严格来说这是有道理的，但不是很宽容。

HTML 表格

Javadoc 中的 HTML 表格？考虑这个有效的 HTML：

 /**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

这现在失败并显示错误消息 no summary or caption for table 。一种快速解决方法是这样做：

 /**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

但为什么这一定是 Javadoc 工具的一个停止世界的错误打败了我？

现在由于更明显的原因而失败的事情

1. 无效链接，例如 {@link notexist}
2. 格式错误的 HTML，例如 always returns <code>true<code> if ...

更新

链接：

Stephen Colebourne 关于该主题的优秀博客。

原文由 peterh 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

目前，我知道 在使用 Maven 时解决更严格的 Java 8 Javadoc 的最简单方法是停用它。

由于参数 -Xdoclint:none 仅存在于 Java 8 中，因此定义此参数会破坏任何其他 Java 的构建。为防止这种情况，我们可以创建一个仅对 Java 8 有效的配置文件，以确保我们的解决方案无论 Java 版本如何都能正常工作。

 <profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

只需将其添加到您的 POM 中即可。

---

对于 maven-javadoc-plugin 3.0.0 用户：

代替

<additionalparam>-Xdoclint:none</additionalparam>

经过

<doclint>none</doclint>

谢谢@banterCZ！

原文由 Fred Porciúncula 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

如果您使用的是 maven javadoc 插件，则可以使用 failOnError 选项来防止它在发现任何 html 错误时停止：

 <plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

或者你可以完全停用严格的 html 选项：

 <plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

欲了解更多 信息。

原文由 assylias 发布，翻译遵循 CC BY-SA 3.0 许可协议