使用Maven时如何解决更严格的Java 8 Javadoc

Question

您会很快意识到JDK8在Javadoc方面要严格得多（默认情况下）。（链接
-请参阅最后一个要点）

如果您从不生成任何Javadoc，那么您当然不会遇到任何问题，但是Maven发布过程之类的内容以及您的CI构建可能会突然失败，因为它们在JDK7上可以正常使用。现在，任何检查Javadoc工具的退出值的操作都将失败。warnings与JDK7相比，JDK8
Javadoc可能也更冗长，但这不是这里的范围。我们正在谈论errors！

存在此问题是为了收集有关如何处理的建议。最好的方法是什么？这些错误是否应该在源代码文件中一劳永逸地解决？如果您有庞大的代码库，则可能需要大量工作。还有哪些其他选择？

也欢迎您评论以前失败的失败案例。

现在失败的恐怖故事

wsimport工具

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

@author标签

我正在打开3-4岁的源代码文件，并看到以下内容：

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

现在由于<字符而失败。严格来说，这是合理的，但不是很宽容。

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工具引起的世界性错误呢？

现在由于更明显的原因而失败的事情

1. 无效的链接，例如 {@link notexist}
2. 格式错误的HTML，例如 always returns <code>true<code> if ...

更新

链接：

Stephen
Colebourne撰写的关于该主题的优秀博客。

Answer 1

目前，我知道 使用Maven时解决更严格的Java 8 Javadoc 的最简单方法是停用它。

由于该参数-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中就可以了。

对于maven-javadoc-plugin 3.0.0用户：

更换

<additionalparam>-Xdoclint:none</additionalparam>

通过

<doclint>none</doclint>

谢谢@banterCZ！