问题
你很快就会发现JDK8在Javadoc方面要严格得多(默认情况下)。 (link-见最后一个要点)
如果你从来没有生成任何Javadoc,那么你当然不会遇到任何问题,但Maven发布过程和可能你的CI构建之类的东西会突然失败,因为他们使用JDK7工作得很好。任何检查Javadoc工具退出值的东西现在都会失败。与JDK7相比,JDK8 Javadoc在warnings
方面可能更加冗长,但这不是这里的范围。我们正在谈论errors
!
存在这个问题是为了收集有关如何处理的提案。什么是最好的方法?是否应该在源代码文件中一劳永逸地修复这些错误?如果你有一个庞大的代码库,这可能需要做很多工作。还有哪些其他选择?
你也可以评论以前通过的失败的故事。
##现在失败的恐怖故事
wsimport工具
wsimport
tool是用于创建Web服务使用者的代码生成器。它包含在JDK中。即使你使用来自JDK8的wsimport
工具,它仍将生成源代码that cannot be compiled with the javadoc compiler from JDK8。
@author标签
我打开3-4岁的源代码文件,看到这个:
/**
* My very best class
* @author John <john.doe@mine.com>
*/
现在由于<字符而失败。严格来说,这是合理的,但不是很宽容。
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工具的一个世界上的错误击败我?
##现在因为更明显的原因而失败的事情
- 无效的链接,例如{@link notexist}
- 格式错误的HTML,例如总是返回<code> true <code> if ...
##更新
链接:
Excellentblog on the subjectbyStephen Colebourne。
#1 热门回答(48 赞)
就目前而言,当我使用Mavenis停用它时,我知道绕过更严格的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!
#2 热门回答(48 赞)
如果你正在使用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>
更多info。
#3 热门回答(2 赞)
我喜欢@ThiagoPorciúncula的解决方案,但它对我来说还不够远。
我通常已经有javadoc pluginadditionalparam
set没有被配置文件覆盖。因此,我不得不:
- 默认情况下,将disableDoclint属性设置为空。
- 如果在java> = 8中,则将disableDoclint属性设置为-Xdoclint:none
- 在themaven-javadoc-plugin`的附加部分中使用$ 。
这似乎工作得很好,虽然冗长。
<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下不会导致语法错误。哇喔!