maven:java8下當javadoc有編譯錯誤時沒法生成.jar包的問題

以前一直在java 7下編譯maven項目,遇到javadoc編譯提示代碼註釋中有錯誤(好比鏈接無效)，也能正常生成javadoc jar包。但最近將編譯器換成java 8後，一樣的命令執行，遇到javadoc編譯錯誤，maven就停止執行，生成jar包失敗了。

在stackoverflow上找到這篇文章，才搞明白緣由：《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>
        <!--引入javadoc插件 -->
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <configuration>
            <show>package</show>
            <!-- 禁用java 8 的DocLint新特性，以確保當javadoc有編譯錯誤時，也能正常生成javadoc jar包-->
            <doclint>none</doclint>
        </configuration>
    </plugin>
</plugins>
但實際測試發現，採用這種方式執行mvn javadoc:jar確實是有效的但在執mvn release:prepare作發佈版本準備時，卻沒有生成javadoc jar 包,使用<additionalparam>-Xdoclint:none</additionalparam>代替doclint參數纔算正常：

<plugins>
    <plugin>
        <!--引入javadoc插件 -->
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.0.1</version>
        <configuration>
            <show>package</show>
            <!-- 禁用java 8 的DocLint新特性，以確保當javadoc有編譯錯誤時，也能正常生成javadoc jar包-->
            <additionalparam>-Xdoclint:none</additionalparam>
        </configuration>
    </plugin>
</plugins>
改爲這樣後，在java 8下執行mvn release:prepare是正常了，但在java 7下會報錯誤:不支持的選項-Xdoclint:none。因此若是但願在java 7,java 8下都能正常執行release，須要使用profile來區分JDK版本。刪除前面在build/plugins中添加的javadoc插件，改成在pom.xml中添加profiles，以下：

</project>
    ....
    <profiles>        
        <profile>
            <id>doclint-java8-disable</id>
            <!-- 指定profile只在JDK版本大於等於1.8時有效-->
            <activation>
                <jdk>[1.8,)</jdk>
            </activation>

            <build>
                <pluginManagement>
                    <plugins>
                        <!--引入javadoc插件 -->
                        <plugin>
                            <groupId>org.apache.maven.plugins</groupId>
                            <artifactId>maven-javadoc-plugin</artifactId>
                            <version>2.9</version>
                            <configuration>
                                <!-- 禁用java 8 的DocLint新特性，以確保當javadoc有編譯錯誤時，也能正常生成javadoc jar包-->
                                <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
---------------------