如何在使用 Maven 时绕过更严格的 Java8Javadoc

您很快就会意识到 JDK8对 Javadoc 的要严格得多(默认情况下)。(链接-参见最后一个要点)

如果您从未生成任何 Javadoc，那么当然您不会遇到任何问题，但是像 Maven 发布过程和可能您的 CI 构建会突然失败，因为它们在 JDK7中工作得很好。任何检查 Javadoc 工具退出值的操作现在都将失败。与 JDK7相比，JDK8 Javadoc 在 warnings方面可能也更详细，但这不是这里的范围。我们说的是 errors！

这个问题的存在是为了收集关于如何解决这个问题的建议。最好的方法是什么？应该在源代码文件中一劳永逸地修复这些错误吗？如果您有一个庞大的代码库，这可能是一项很大的工作。还有别的选择吗？

我们也欢迎你们评论那些现在失败了，以前会通过的故事。

现在失败的恐怖故事

Wsimport 工具

wsimport工具是用于创建 Web 服务使用者的代码生成器。它包含在 JDK 中。即使您使用来自 JDK8的 wsimport工具，它仍然会生成源代码 不能用 JDK8的 javadoc 编译器进行编译。

@ author tag

我打开3-4年前的源代码文件，看到这个:

/**
* My very best class
* @author John <john.doe@mine.com>
*/

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

HTML 表格

HTML 表在你的 Javadoc? 考虑这个有效的 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 工具的“停止世界”(stop-the-world)错误会打败我呢? ？

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

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

更新

相关网址:

优秀的 关于这个话题的博客由 斯蒂芬 · 科尔伯恩。

51840 次浏览
小开

如果您使用的是 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>

为了更多的 信息。

小开
最佳答案

目前，我所知道的解决 在使用 Maven 时，需要绕过更严格的 Java8Javadoc最简单的方法就是关闭它。

由于参数 -Xdoclint:none只存在于 Java8中，因此定义此参数将破坏其他 Java 的构建。为了防止这种情况发生，我们可以创建一个只对 Java8有效的概要文件，确保我们的解决方案不管 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！

小开

我喜欢@ThiagoPorci úncula 的解决方案，但它对我来说还不够。

我通常已经有 javadoc 插件 additionalparam设置没有被覆盖的配置文件。因为这个，我不得不:

  • 默认情况下将 disableDoclint属性设置为空。
  • 如果在 java > = 8中，将 disableDoclint属性设置为 -Xdoclint:none
  • 在 maven-javadoc-plugin的 additionalparam部分中使用 ${disableDoclint}。

这似乎工作得很好，虽然冗长。

<properties>
<!-- set empty property -->
<disableDoclint></disableDoclint>
</properties>
<profiles>
<profile>
<id>disable-java8-doclint</id>
<activation>
<jdk>[1.8,)</jdk>
</activation>
<properties>
<!-- set property if >= java 8 -->
<disableDoclint>-Xdoclint:none</disableDoclint>
</properties>
</profile>
...
</profiles>

然后在下面我可以使用我已经定义的 additionalparam部分中的可选 ${disableDoclint}变量。

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<showPackage>false</showPackage>
<additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
</configuration>
</execution>
</executions>
<configuration>
<showPackage>false</showPackage>
<bottom>This documentation content is licensed...</bottom>
<additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
</configuration>
</plugin>

这在 java 8下可以工作，但是在 java 7下不会导致语法错误！

小开

由于 maven-javadoc-plugin 的版本3.0.0，文档通过专用的 XML 标记进行配置 

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
<configuration>
<doclint>none</doclint>
</configuration>
</plugin>
小开

注意，对于错误 no summary or caption for table，使用 <table summary="">将不再有效。如果是这种情况，向表中添加一个 <caption>元素，如下所示:

<table>
<caption>Examples</caption>
...
</table>

希望这能帮到别人，我花了很长时间才发现。


提交答案