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

Posted 2023-02-26

【中文标题】使用 Maven 时如何解决更严格的 Java 8 Javadoc

【英文标题】：How to work around the stricter Java 8 Javadoc when using Maven

【发布时间】：2014-04-27 01:12:00

【问题描述】：

您很快就会意识到 JDK8 对 Javadoc 的要求要严格得多（默认情况下）。 （link - 见最后一个要点）

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

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

也欢迎您对现在失败的故事发表评论。

现在失败的恐怖故事

wsimport 工具

wsimport 工具是用于创建 Web 服务消费者的代码生成器。它包含在 JDK 中。即使您使用 JDK8 中的 wsimport 工具，它仍然会生成源代码 that cannot be compiled with the javadoc compiler from JDK8。

@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 工具的停止世界错误打败了我？？

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

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

更新

链接：

优秀的blog on the subjectStephen Colebourne。

【问题讨论】：

这个博客展示了如何关闭它：blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

您可以使用-Xdoclint 甚至使用javac 告诉它在编译时检查文档...

@HimanshuBhardwaj。感谢您链接到 Stephen Colebourne 的博客。到目前为止我读过的关于这个主题的最好的文章！

另外一个“错误”也是错误的：'bad usage of '>' -- 这是错误的，'>' 在 XML 中是完全可以接受的，除了特定的 ']] >' 不被接受（其中一个字符必须被转义）。只有 '' 确实有助记符 (gt) 为方便起见，但它的使用是完全可选的。

我想知道 HTML 4 的合规性而不是 HTML 5 有何不同。就个人而言，我更喜欢简单的标记语言，因为我必须阅读源代码而不仅仅是漂亮的输出；至少对我而言，HTML 的人类可读性是值得商榷的。

【参考方案1】：

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

由于参数-Xdoclint:none 仅存在于 Java 8 中，因此定义此参数会破坏任何其他 Java 的构建。为防止这种情况，我们可以创建一个仅对 Java 8 有效的配置文件，以确保我们的解决方案无论 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！

【讨论】：

我会接受这是我们大多数人将实施的最可能的解决方案。我喜欢<activation> 部分。但我希望有人能想出一个工具，它可以遍历那些源文件并帮助开发人员修复错误……而不是仅仅关闭 DocLint。

如果您依赖另一个配置文件同时默认处于活动状态（使用 activeByDefault=true），请注意使用此解决方案。

@peterh：完全记录所有内容是没有意义的，这是一项无用的重复工作，根据干净的代码原则，建议只记录不明显的内容和公共 API。

这不适用于 maven-javadoc-plugin 版本 3.0.0。我必须回到版本 3.0.0-M1 才能使 -Xdoclint:none 工作。

@MehradSadegh 对于 maven-javadoc-plugin 版本 3.0.0 只需将 <additionalparam>-Xdoclint:none</additionalparam> 替换为 <doclint>none</doclint>

【参考方案2】：

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

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

了解更多info。

【讨论】：

嗯。这些解决方案的问题在于，如果您使用 JDK8 Javadoc 来考虑它，您会希望 not 因错误而失败，而使用 JDK7 Javadoc 则需要。因此，出于这个原因，我最喜欢-Xdoclint 选项。如果使用 JDK7 Javadoc 执行，希望它会被忽略吗？

您可以通过键入 Java 版本的 maven 配置文件有条件地应用该选项...？

不，使用 JDK7 失败并显示 javadoc：错误 - 无效标志：-Xdoclint:none（Oracle 做得很好）。

【参考方案3】：

请注意，对于错误no summary or caption for table，使用<table summary=""> 将不再起作用。如果这是您的情况，请将 <caption> 元素添加到您的表中，如下所示：

<table>
    <caption>Examples</caption>
    ...
</table>

希望这可以帮助那里的人。我花了一段时间才发现这一点。

【讨论】：

什么版本的JDK？当然，<table summary=""> 技巧仍然适用于 JDK8。 （刚刚在jdk1.8.0_201上测试过）

@peterh 我用的是 jdk 11。

这是最新的答案。 summary="..." 属性不再支持 HTML5（JDK 11 javadoc 的默认输出）。 JDK 8 也支持它。

【参考方案4】：

从 maven-javadoc-plugin 3.0.0 版开始，doclint 是通过专用的 XML 标签配置的

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>

【参考方案5】：

我喜欢@ThiagoPorciúncula 的解决方案，但对我来说还远远不够。

我通常已经设置了 javadoc 插件additionalparam，这些插件没有被配置文件覆盖。因此，我不得不：

将disableDoclint 属性默认设置为空。 如果在 java 中 >= 8，则将 disableDoclint 属性设置为 -Xdoclint:none 使用$disableDoclint in theadditionalparamsection of themaven-javadoc-plugin`。

这似乎运作良好，虽然很冗长。

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

然后在下面我可以在我已经定义的additionalparam 部分中使用可选的$disableDoclint 变量。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X $disableDoclint</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X $disableDoclint</additionalparam>
    </configuration>
</plugin>

这在 java 8 下有效，但在 java 7 下不会导致语法错误。哇哦！