如何在使用Maven时规避更严格的Java 8 Javadoc要求

Question

你很快会意识到，在Javadoc方面，JDK8默认情况下更加严格。（链接 - 参见最后一条）

如果你从未生成过任何Javadoc，那么当然不会遇到任何问题，但是像Maven发布过程和可能的CI构建之类的东西将会突然失败，而它们在JDK7中运行得非常好。任何检查Javadoc工具退出值的东西都将无法通过。JDK8 Javadoc可能也比JDK7在警告方面更加冗长，但这不是本文的重点。我们正在谈论错误！

此问题旨在收集有关如何处理此问题的建议。最好的方法是什么？这些错误是否应该在源代码文件中修复？如果您有一个庞大的代码库，这可能需要大量的工作。还有哪些其他选项？

欢迎您在评论中分享以前可以通过的故事。

现在失败的恐怖故事

wsimport工具

wsimport工具是用于创建Web服务消费者的代码生成器。它包含在JDK中。即使您使用来自JDK8的wsimport工具，它仍然会生成源代码无法使用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撰写的优秀博客文章。

- peterh

---

这篇博客展示了如何关闭JDK 8 Javadoc中的Doclint功能：http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html。 - Himanshu Bhardwaj

你甚至可以在使用javac时使用“-Xdoclint”指令，让编译器在编译时检查文档。 - Holger

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

此外，“errors”中的一个也是错误的：“'bad usage of '>'”--这是错误的，在XML中“>”是完全可以接受的，除了特定的“]]>”序列不被接受（其中一个字符必须被转义）。只有“<”必须被转义，“>”具有助记符（gt）以方便使用，但其使用完全是可选的。 - StaxMan

我想知道为什么要使用HTML 4而不是HTML 5。就我个人而言，我更喜欢一种简单的标记语言，因为我需要阅读源代码而不仅仅是漂亮的输出；至少对我来说，HTML的可读性是有争议的。 - Daniel

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

- Fred Porciúncula

---

我会尽力将这句话翻译为通俗易懂的语言，同时保持原意不变：我会接受这个最有可能被我们大多数人采用的解决方案。我喜欢"<activation>" 部分。但我希望有人能够开发出一种工具，可以遍历那么多源文件，并协助开发人员修复错误……而不仅仅是关闭DocLint。 - peterh

@peterh：记录所有内容是没有意义的，这是无用的重复工作。根据清晰代码原则，建议仅记录不明显的部分和公共API。 - Daniel Hári

这在maven-javadoc-plugin版本3.0.0上不起作用。我不得不回到版本3.0.0-M1才能使-Xdoclint：none正常工作。 - Mehrad Sadegh

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

是的，添加与JDK 8相关的配置文件并设置<doclint>none</doclint>解决了这个问题。它生成的javadoc jar与在JDK 7中生成的相同。谢谢。 - Saurabhcdt

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

更多信息请参阅。

- assylias

---

这些解决方案的问题在于，如果你使用JDK8 Javadoc，你不希望出现错误，而如果你使用JDK7 Javadoc，则需要出现错误。因此，出于这个原因，我最喜欢-Xdoclint选项。希望如果使用JDK7 Javadoc执行时，它会被静默忽略。 - peterh

你可以通过一个基于Java版本的Maven配置文件有条件地应用该选项吗？ - Donal Fellows

抱歉，使用JDK7时，使用javadoc命令时会出现错误：“invalid flag: -Xdoclint:none”（Oracle做得好啊）。 - Giovanni Toraldo

Answer 3

请注意，对于错误 no summary or caption for table ，使用<table summary="">将不再起作用。 如果您遇到这种情况，请向表格添加<caption>元素，例如：

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

希望这对某些人有所帮助。我花了一段时间才弄明白这个问题。

- Jeronimo Backes

---

JDK的哪个版本？肯定<table summary="">技巧在JDK8上仍然有效。（刚在jdk1.8.0_201上测试过） - peterh

@peterh 我使用的是jdk 11。 - Jeronimo Backes

这是最新的答案。在HTML5中（JDK 11 javadoc的默认输出），不再支持summary="..."属性。但它仍然被JDK 8支持。 - kap

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

- Vlad Isajkin

Answer 5

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

通常我已经设置了javadoc插件additionalparam，但这些参数并没有被配置文件覆盖。因此，我需要：

• 将disableDoclint属性默认设置为空。
• 如果在java >= 8中，则将disableDoclint属性设置为-Xdoclint:none
• 在maven-javadoc-plugin的additionalparam部分使用${disableDoclint}。

这似乎很好用，尽管有点啰嗦。

<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中不会导致语法错误。太棒了！

- Gray