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


133

您很快就会意识到,就Javadoc而言,JDK8更为严格(默认情况下)。(链接 -参见最后一个要点)

如果您从不生成任何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 ...

更新

链接:

Stephen Colebourne撰写的关于该主题的优秀博客



1
-Xdoclint甚至可以使用javac告诉它在编译时检查文档…
Holger 2014年

1
@HimanshuBhardwaj。感谢您链接到Stephen Colebourne的博客。到目前为止,我读过的最好的文章!
彼得2014年

此外,“错误”之一也是错误的:“'>'的用法错误-这是错误的,在XML中,'>'是完全可以接受的,但不接受']]>'的特定顺序(一个字符必须转义)。为了方便起见,只有'<'必须转义,'>'确实具有助记符(gt),但其使用完全是可选的。
StaxMan 2015年

我想知道与HTML 4兼容而不是HTML 5是什么。就个人而言,我更喜欢一种简单的标记语言,因为我必须阅读源代码,而不仅仅是漂亮的输出。至少对我来说,HTML的人类可读性值得商bat。
丹尼尔(Daniel)

Answers:


56

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


3
我会将此作为我们大多数人将要实施的最有可能的解决方案。我喜欢这个<activation>部分。但是,我希望有人能提出一个可以遍历那么多源文件并帮助开发人员修复错误的工具,而不仅仅是关闭DocLint。
peterh '16

如果您依赖默认情况下同时处于活动状态的另一个配置文件(使用activeByDefault = true),请当心使用此解决方案。
mwhs

1
@peterh:完全记录所有内容是没有意义的,那是无用的重复工作,按照干净的代码原则,建议仅记录不明显的内容和公共API。
丹尼尔·哈里(DanielHári)'17

1
这不适用于maven-javadoc-plugin版本3.0.0。我必须回到3.0.0-M1版本才能使-Xdoclint:none工作。
Mehrad Sadegh's

4
@MehradSadegh对于maven-javadoc-plugin版本3.0.0只需替换<additionalparam>-Xdoclint:none</additionalparam><doclint>none</doclint>
banterCZ

53

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

有关更多信息


2
嗯 这些解决方案的问题是,如果你认为它与JDK8的Javadoc你想而用JDK7的Javadoc你失败的错误。因此,出于这个原因,我最喜欢该-Xdoclint选项。希望如果使用JDK7 Javadoc执行它将被默默地忽略?
peterh 2014年

2
您可以通过键入Java版本的Maven概要文件有条件地应用该选项...?
Donal Fellows 2014年

14
不,对于JDK7,它会失败,并显示javadoc:错误-无效标志:-Xdoclint:none(Oracle不错的工作)。
Giovanni Toraldo 2014年

4

从3.0.0版的maven-javadoc-plugin开始,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>

3

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

我通常已经additionalparam设置了javadoc插件集,该插件集不会被配置文件覆盖。因此,我不得不:

  • disableDoclint属性默认设置为空。
  • 如果在Java> = 8中,则将disableDoclint属性设置为-Xdoclint:none
  • 使用${disableDoclint} in theadditionalparam section of 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>

然后在下面,我可以${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下不会引起语法错误。


2

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

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

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


1
什么版本的JDK?当然,该<table summary="">技巧仍然可以在JDK8上使用。(刚刚在jdk1.8.0_201上进行了测试)
peterh,

@peterh我使用JDK 11
杰罗尼莫BACKES

1
这是最新的答案。summary="..."HTML5(JDK 11 javadoc的默认输出)不再支持此属性。它也支持JDK 8
KAP
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.