在使用Maven时如何解决更严格的Java 8 Javadoc
当谈到Javadoc时,您很快就会意识到JDK8更严格(默认情况下)。 (链接 - 请参阅最后一点)
如果你永远不会生成任何Javadoc,那么当然你不会遇到任何问题,但是像Maven发布过程和可能的CI构建会突然失败,因为它们在JDK7中工作得很好。 任何检查Javadoc工具出口值的东西现在都会失败。 与JDK7相比,JDK8 Javadoc可能在warnings
方面更加冗长,但这不在此处。 我们正在谈论errors
!
这个问题的存在是为了收集如何处理这个问题的建议。 什么是最好的方法? 这些错误是否应该在源代码文件中一劳永逸地解决? 如果你有一个庞大的代码库,这可能是很多工作。 还有什么其他选择?
你也欢迎评论现在失败的事情。
现在失败的恐怖故事
wsimport工具
wsimport
工具是用于创建Web服务消费者的代码生成器。 它包含在JDK中。 即使您使用JDK8中的wsimport
工具,它仍会产生无法使用JDK8中的javadoc编译器编译的源代码。
@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}
always returns <code>true<code> if ...
UPDATE
链接:
Stephen Colebourne关于这个主题的优秀博客。
就目前而言,我知道在使用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!
如果您使用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>
欲了解更多信息。
我喜欢@ThiagoPorciúncula的解决方案,但对我来说还不够。
我通常已经有javadoc插件additionalparam
设置没有被配置文件覆盖。 正因为如此,我不得不:
disableDoclint
属性默认设置为空。 disableDoclint
属性设置为-Xdoclint:none
section of the
maven-javadoc-plugin` ${disableDoclint} in the
additionalparam section of the
使用${disableDoclint} in the
。 这似乎很好,尽管冗长。
<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下的语法错误。Woo hoo!
链接地址: http://www.djcxy.com/p/91891.html上一篇: How to work around the stricter Java 8 Javadoc when using Maven