1.背景:
平时在jdk7环境使用时,一些注解不是很严格,在升级到8时,使用Maven-javadoc-plugin插件打包报错,Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:jar (attach-javadocs) on project p-jiazhuang-api: MavenReportException: Error while generating Javadoc:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:jar (attach-javadocs) on project p-jiazhuang-api: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - D:\16project\respo\p-jiazhuang\p-jiazhuang-api\src\main\java\com\chinaredstar\jiazhuang\api\ActivityServiceApi.java:19: 警告: @param 没有说明
[ERROR] * @param registration
[ERROR] ^
[ERROR] D:\16project\respo\p-jiazhuang\p-jiazhuang-api\src\main\java\com\chinaredstar\jiazhuang\api\ActivityServiceApi.java:10: 警告: 非法标识: Author
[ERROR] * @Author ***
2.方案:
在JDK 8中,Javadoc中添加了doclint,而这个工具的主要目的是旨在获得符合W3C HTML 4.01标准规范的HTML文档,在JDK 8中,已经无法获取如下的Javadoc,除非它满足doclint:
不能有自关闭的HTML tags,例如<br/>或者<a id="x"/>
不能有未关闭的HTML tags,例如有<ul>而没有</ul>
不能有非法的HTML end tags,例如</br>
不能有非法的HTML attributes,需要符合doclint基于W3C HTML 4.01的实现
不能有重复的HTML id attribute
不能有空的HTML href attribute
不能有不正确的嵌套标题,例如类的文档说明中必须有<h3>而不是<h4>
不能有非法的HTML tags,例如List<String>需要用<>对应的实体符号
不能有损坏的@link references
不能有损坏的@param references,它们必须匹配实际的参数名称
不能有损坏的@throws references,第一个词必须是一个类名称
注意违反这些规则的话,将不会得到Javadoc的输出。
虽然标准很好,但是在实际开发中,一般都无需这么严格的,这样就要做降级处理的。关闭doclint即可:
<profiles>
<profile>
<id>disable-javadoc-doclint</id>
<activation>
<jdk>[1.8,)</jdk>
</activation>
<properties>
<javadoc.opts>-Xdoclint:none</javadoc.opts>
</properties>
</profile>
</profiles>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<executions>
<execution>
<id>attach-javadocs</id>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
<configuration>
<additionalparam>${javadoc.opts}</additionalparam>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
以上方式是兼用了不同环境的方式。如果无需关系环境切换的问题。直接plugin配置即可: <additionalparam>-Xdoclint:none</additionalparam>
3.IDEA中操作:
在配置了profile后。在idea中会出现如下disable-javadoc-dolint选项:
勾选disable-javadoc-dolint选项;然后点击选中所要打包的项目下package。右键弹出框选中 Create XXXXX-api[package] 进入如下选项框:
表示将以disable-javadoc-dolint下打包。点击ok即可。然后在package双击,就会打包的。
也可以在头部配置:
点击下拉开 Edit Configrations,出现弹出框:
在这里配置,完成后运行即可。