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

问题

你很快就会发现JDK8在Javadoc方面要严格得多(默认情况下)。 (link-见最后一个要点)

如果你从来没有生成任何Javadoc,那么你当然不会遇到任何问题,但Maven发布过程和可能你的CI构建之类的东西会突然失败,因为他们使用JDK7工作得很好。任何检查Javadoc工具退出值的东西现在都会失败。与JDK7相比,JDK8 Javadoc在warnings方面可能更加冗长,但这不是这里的范围。我们正在谈论errors

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

你也可以评论以前通过的失败的故事。

##现在失败的恐怖故事

wsimport工具

wsimporttool是用于创建Web服务使用者的代码生成器。它包含在JDK中。即使你使用来自JDK8的wsimport工具,它仍将生成源代码that cannot be compiled with the javadoc compiler from JDK8

@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工具的一个世界上的错误击败我?

##现在因为更明显的原因而失败的事情

  • 无效的链接,例如{@link notexist}
  • 格式错误的HTML,例如总是返回<code> true <code> if ...

##更新

链接:

Excellentblog on the subjectbyStephen Colebourne


#1 热门回答(48 赞)

就目前而言,当我使用Mavenis停用它时,我知道绕过更严格的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!


#2 热门回答(48 赞)

如果你正在使用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


#3 热门回答(2 赞)

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

我通常已经有javadoc pluginadditionalparamset没有被配置文件覆盖。因此,我不得不:

  • 默认情况下,将disableDoclint属性设置为空。
  • 如果在java> = 8中,则将disableDoclint属性设置为-Xdoclint:none
  • 在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下不会导致语法错误。哇喔!