maven:java8下当javadoc有编译错误时无法生成.jar包的问题

- 日理万妓 2022-03-27 12:51 333阅读 0赞

之前一直在java 7下编译maven项目,遇到javadoc编译提示代码注释中有错误(比如连接无效)，也能正常生成javadoc jar包。但最近将编译器换成java 8后，同样的命令执行，遇到javadoc编译错误，maven就中止执行，生成jar包失败了。

在stackoverflow上找到这篇文章，才搞明白原因：[《Maven is not working in Java 8 when Javadoc tags are incomplete》][Maven is not working in Java 8 when Javadoc tags are incomplete]

原来是java 8的DocLint新特性造成的：  
java 8中javadoc提供了一个新特性，允许程序能检测到java 代码注释中的错误(之前的版本，javadoc调用方无法检测到代码注释中的错误)，默认情况下这个特性是打开的，所以maven执行编译javadoc编译时遇到代码注释中有错误，就会抛出异常，并中止执行。

最简单的解决办法：升级`maven-javadoc-plugin`插件版本到3.0.0以上，并添加`<doclint>none</doclint>`参数禁用该特性  
示例如下

<plugins>
    	<plugin>
    		
    		<groupId>org.apache.maven.plugins</groupId>
    		<artifactId>maven-javadoc-plugin</artifactId>
    		<version>3.0.1</version>
    		<configuration>
    			<show>package</show>
    			
    			<doclint>none</doclint>
    		</configuration>
    	</plugin>
    </plugins>

但实际测试发现，采用这种方式执行`mvn javadoc:jar`确实是有效的但在执`mvn release:prepare`做发布版本准备时，却没有生成javadoc jar 包,使用`<additionalparam>-Xdoclint:none</additionalparam>`代替`doclint`参数才算正常：

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

改成这样后，在java 8下执行`mvn release:prepare`是正常了，但在java 7下会报错误:不支持的选项`-Xdoclint:none`。所以如果希望在java 7,java 8下都能正常执行release，需要使用profile来区分JDK版本,并将javadoc插件的版本改为2.9。删除前面在`build/plugins`中添加的javadoc插件，改为在`pom.xml`中添加profiles，如下：

</project>
    	....
    	<profiles>		
    		<profile>
    			<id>doclint-java8-disable</id>
    			
    			<activation>
    				<jdk>[1.8,)</jdk>
    			</activation>
    
    			<build>
    				<pluginManagement>
    					<plugins>
    						
    						<plugin>
    							<groupId>org.apache.maven.plugins</groupId>
    							<artifactId>maven-javadoc-plugin</artifactId>
    							<version>2.9</version>
    							<configuration>
    								
    								<additionalparam>-Xdoclint:none</additionalparam>
    							</configuration>
    						</plugin>
    					</plugins>
    				</pluginManagement>
    			</build>
    		</profile>
    	</profiles>
    </project>

# 参考资料 #

[Maven is not working in Java 8 when Javadoc tags are incomplete][]  
[maven javadoc-mojo][]  
[java 8 doclint][]  
[DocLint is a new feature in Java 8][]  
[How to ignore Maven build erros due to JavaDoc with Java 8][]

[Maven is not working in Java 8 when Javadoc tags are incomplete]: https://stackoverflow.com/questions/15886209/maven-is-not-working-in-java-8-when-javadoc-tags-are-incomplete
[maven javadoc-mojo]: https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html
[java 8 doclint]: https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#BEJEFABE
[DocLint is a new feature in Java 8]: http://openjdk.java.net/jeps/172
[How to ignore Maven build erros due to JavaDoc with Java 8]: https://www.locked.de/how-to-ignore-maven-javadoc-errors-in-java-8/