在使用Maven时如何解决更严格的Java 8 Javadoc

您将很快意识到，对于Javadoc，JDK8更严格（默认情况下）。 （ 链接 – 见最后一点）

如果你从来没有生成任何Javadoc，那么当然你不会遇到任何问题，但像Maven发布过程和可能你的CI构build会突然失败，他们在JDK7中工作得很好。 任何检查Javadoc工具出口值的东西现在都会失败。 与JDK7相比，JDK8 Javadoc在warnings方面可能也更加冗长，但这不在此处。 我们在谈论errors ！

这个问题是为了收集如何处理这个问题的build议。 什么是最好的方法？ 这些错误是否应该在源代码文件中一劳永逸地解决？ 如果你有一个庞大的代码库，这可能是很多工作。 还有什么其他的select？

你也欢迎评论现在失败的事情。

现在失败的恐怖故事

wsimport工具

wsimport工具是创buildWeb服务使用者的代码生成器。 它包含在JDK中。 即使使用JDK8中的wsimport工具，它也会产生无法使用JDK8中的javadoc编译器编译的源代码。

@author标签

我打开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 ...

UPDATE

链接：

Stephen Colebourne 关于这个主题的博客 。

Answer 1

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

由于参数-Xdoclint:none只存在于Java 8中，因此定义此参数将打破其他任何Java的构build。 为了防止这种情况发生，我们可以创build一个只适用于Java 8的configuration文件，确保我们的解决scheme无论Java版本如何。

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

只要把它添加到你的POM中，你就可以走了。

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> 

欲了解更多信息 。

Answer 3

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

我通常已经有javadoc插件additionalparam设置没有被configuration文件覆盖。 正因为如此，我不得不：

• 将disableDoclint属性设置为默认为空。
• 如果在java> = 8中，将disableDoclint属性设置为-Xdoclint:none
• section of the maven-javadoc-plugin` ${disableDoclint} in the additionalparam section of the使用${disableDoclint} in the 。

这似乎工作得很好，尽pipe冗长。

 <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}variables。

 <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下的语法错误。