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

当谈到Javadoc时,您很快就会意识到JDK8更严格(默认情况下)。 (链接 - 请参阅最后一点)

如果你永远不会生成任何Javadoc,那么当然你不会遇到任何问题,但是像Maven发布过程和可能的CI构建会突然失败,因为它们在JDK7中工作得很好。 任何检查Javadoc工具出口值的东西现在都会失败。 与JDK7相比,JDK8 Javadoc可能在warnings方面更加冗长,但这不在此处。 我们正在谈论errors

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

你也欢迎评论现在失败的事情。

现在失败的恐怖故事

wsimport工具

wsimport工具是用于创建Web服务消费者的代码生成器。 它包含在JDK中。 即使您使用JDK8中的wsimport工具,它仍会产生无法使用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工具的世界末日的错误才能击败我?

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

  • 无效的链接,例如{@link notexist}
  • 格式不正确的HTML,例如always returns <code>true<code> if ...
  • UPDATE

    链接:

    Stephen Colebourne关于这个主题的优秀博客。


    就目前而言,我知道在使用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!


    如果您使用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>
    

    欲了解更多信息。


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

    我通常已经有javadoc插件additionalparam设置没有被配置文件覆盖。 正因为如此,我不得不:

  • disableDoclint属性默认设置为空。
  • 如果在java> = 8中,将disableDoclint属性设置为-Xdoclint:none
  • section of the maven-javadoc-plugin` ${disableDoclint} in the additionalparam section of the使用${disableDoclint} in the
  • 这似乎很好,尽管冗长。

    <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下的语法错误。Woo hoo!

    链接地址: http://www.djcxy.com/p/91891.html

    上一篇: How to work around the stricter Java 8 Javadoc when using Maven

    下一篇: Java: Using ConcurrentHashMap as a lock manager