在使用 Maven 时，如何解决更严格的 Java 8 Javadoc 问题

java maven java-8

2022-08-31 08:04:10

您很快就会意识到，当涉及到Javadoc时，JDK8（默认情况下）要严格得多。（链接 - 请参阅最后一个项目符号点）

如果你从未生成任何Javadoc，那么你当然不会遇到任何问题，但是像Maven发布过程和可能的CI构建这样的事情会突然失败，因为它们在JDK7上工作得很好。检查 Javadoc 工具退出值的任何内容现在都将失败。与JDK7相比，JDK8 Javadoc可能也更冗长，但这不是这里的范围。我们正在谈论！warningserrors

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

也欢迎您评论一下以前会失败的故事。

恐怖故事，现在失败了

wsimport tools

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

@author标签

我正在打开3-4岁的源代码文件，并看到这个：

/**
 * My very best class
 * @author John <john.doe@mine.com> 
 */

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

表格

Javadoc 中的 HTML Tables？考虑这个有效的 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工具的停止世界错误？？

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

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

更新

链接：

斯蒂芬·科尔伯恩（Stephen Colebourne）关于该主题的优秀博客。

答案 1

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

由于该参数仅存在于 Java 8 中，因此定义此参数会中断任何其他 Java 的构建。为了防止这种情况，我们可以创建一个仅在Java 8中处于活动状态的配置文件，以确保我们的解决方案无论Java版本如何都能正常工作。-Xdoclint:none

<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！

答案 2

如果您使用的是 maven javadoc 插件，则可以使用该选项来防止它在发现任何 html 错误时停止：failOnError

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

或者，您可以使用以下命令完全停用严格的html选项：

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

有关详细信息。