如何在使用Maven时绕过更严格的Java8 Javadoc

Question

您很快就会意识到，JDK8在Javadoc方面要严格得多（默认情况下）。（链接-参见最后一个项目符号）

如果您从未生成任何Javadoc，那么您当然不会遇到任何问题，但是像Maven发布流程这样的事情，可能还有您的CI构建，在使用JDK7时会突然失败。检查Javadoc工具的exit值的任何操作现在都将失败。与JDK7相比，JDK8 Javadoc在警告方面可能也更冗长，但这不是本文的范围。我们正在讨论错误！

这个问题的存在是为了收集关于该如何做的建议。最好的方法是什么？是否应该在源代码文件中一劳永逸地修复这些错误？如果您有一个庞大的代码库，这可能是一个很大的工作。还有什么其他选择？

同时也欢迎你发表评论，告诉你以前会通过的那些现在失败的故事。

wsimport工具是用于创建web服务使用者的代码生成器。它包含在JDK中。即使使用JDK8中的wsimport工具，它仍然会生成无法使用JDK8中的javadoc编译器编译的源代码。

/**
 * My very best class
 * @author John <[e-mail]> 
 */

由于<字符，此操作现在失败。严格地说，这是有道理的，但不是很宽恕。

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>
 */

1. 无效链接，例如{@link notexist}
2. 格式错误的HTML，例如，如果...
总是返回 true

链接：

Stephen Colebourne写的关于这个主题的优秀博客。




Answer 1

目前，在使用Maven时，我知道的围绕更严格的Java8Javadoc工作的最简单的方法是停用它。

由于参数-xdoclint:none只存在于Java8中，因此定义此参数将破坏任何其他Java的构建。为了防止这种情况，我们可以创建一个仅对Java8有效的配置文件，确保我们的解决方案不管Java版本如何都能工作。

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

只要把它加到你的POM上，你就可以走了。

-xdoclint:none

由

无

谢谢@bantercz！