使用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 <john.doe@mine.com> 
 */

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

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

UPDATE

链接:

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>

有关更多信息.

Answer 3

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

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

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

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