Question

当谈到Javadoc时，你很快就会意识到JDK8更严格（默认情况下）。（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 tag

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

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

现在因为＆lt;字符。严格来说，这是合理的，但不是很宽容。

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 subject的优秀Stephen Colebourne。

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！

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>

了解更多info。

Answer 3

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

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

默认情况下将disableDoclint属性设置为空。
如果在java＆gt; = 8中，请将disableDoclint属性设置为-Xdoclint:none
使用${disableDoclint} in the additionalparam section of the maven-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>

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

<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下不会导致语法错误。哇哇！

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>

Answer 5

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

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

希望这可以帮助某个人。我花了一段时间才找到答案。

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