当Javadoc标记不完整时，Maven无法在Java 8中工作

Question

自从我使用Maven以来，我已经能够在本地存储库中构建和安装具有不完整Javadoc标记（例如，缺少一个参数）的项目。

但是，自从我迁移到Java 8(1.8.0-EA-B90)以来，Maven对于缺少文档标记是绝对严格的，并且当我试图构建或安装一个Javadoc并不“完美”的项目时，会向我展示大量与Javadoc问题相关的Javadoc错误。我试图在本地存储库中编译和安装的一些项目是我无法控制的第三方项目。因此，在我的场景中，仅仅修复所有这些项目中的所有Javadocs的变通方法似乎是不可行的。

这是我在项目中执行MVN clean package Install时看到的输出的一小部分：

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.026s
[INFO] Finished at: Mon Apr 08 21:06:17 CEST 2013
[INFO] Final Memory: 27M/437M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9:jar (attach-javadocs) on project jpc: MavenReportException: Error while creating archive:
[ERROR] Exit code: 1 - /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:10: error: @param name not found
[ERROR] * @param terms the terms to assert
[ERROR] ^
[ERROR] /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:11: warning: no description for @return
[ERROR] * @return
[ERROR] ^

Javadoc Maven插件在我的POM中配置如下：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

就像我之前说的，如果我回到Java七号，一切都很好。也许这是一个与Maven在Java 8中运行有关的bug吗？我怎样才能使它在Java 8中工作（例如，能够构建项目的Javadoc并将其代码安装在我的本地存储库中）呢？我已经在OSX中用Maven 3.0.3和3.0.5进行了测试。

更新：

如果我用 false 更改Javadoc插件配置（谢谢Martin):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

然后将项目安装在我的本地存储库中。但是，仍然没有生成Javadoc JAR。

我在使用这种新配置的控制台中看到的输出片段如下：

[错误]MavenReportException：创建存档时出错：退出代码：1-/Users/....Java：18：警告：no@param...命令行是：/Library/Java/home/bin/javadoc@options@packages

请参阅'/users/sergioc/documents/workspaces/heal/minitoolbox/target/apidocs'目录中生成的Javadoc文件。

在org.apache.maven.plugin.javadoc.abstractjavadocmojo.executejavadoccommandline（abstractjavadocmojo.java:5043)在org.apache.maven.plugin.javadoc.abstractjavadocmojo.executeport（abstractjavadocmojo.java:1990)在org.apache.maven.plugin.javadocjar.execute(javadocjar.java:181)在在org.apache.maven.defaultmaven.doexecute（defaultmaven.java:320)在org.apache.maven.defaultmaven.execute（defaultmaven.java:156)在org.apache.maven.cli.mavencli.execute（defaultmaven.java:537)在org.apache.maven.cli.mavencli.domain（mavencli.java:196)在org.apache.maven.cli.mavencli.domain（mavencli.java:141

关于如何构建源代码、安装项目和生成Javadoc JAR（就像它与Java 7一起工作一样），有什么解决方法吗？

Answer 1

这里是我所知道的忽略doclint警告的最简洁的方法，不管使用的是什么Java版本。不需要在多个配置文件中重复插件配置，只需稍加修改。

<profiles>
  <profile>
    <id>doclint-java8-disable</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9.1</version>
      <executions>
        <execution>
          <id>attach-javadocs</id> <!-- The actual id should be apparent from maven output -->
          <configuration>
            <additionalparam>${javadoc.opts}</additionalparam>
          </configuration>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

在Oracle/Open jdk 6、7、8和11上测试。

Answer 2

让Java 8和Java 7都能工作的最简单的方法是在构建中使用一个概要文件：

<profiles>
  <profile>
    <id>doclint-java8-disable</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <configuration>
            <additionalparam>-Xdoclint:none</additionalparam>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Answer 3

最好的解决方案是修复javadoc错误。如果由于某种原因，这是不可能的（即：自动生成的源代码），那么您可以禁用此检查。

DocLint是《Java 8》中的一个新特性，概括为：

提供一种方法，在开发周期的早期检测Javadoc注释中的错误，并且以一种很容易链接回源代码的方式检测Javadoc注释中的错误。

默认情况下，这是启用的，并且在生成JavaDocs之前将运行大量的检查。您需要按照本线程中的指定，为Java 8关闭此功能。您必须将此添加到maven配置中：

<profiles>
  <profile>
    <id>java8-doclint-disabled</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>
<build>
  <plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
                <configuration>
                    <additionalparam>${javadoc.opts}</additionalparam>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
                <additionalparam>${javadoc.opts}</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
   </plugins>
</build>

对于maven-javadoc-plugin 3.0.0+:替换

<additionalparam>-Xdoclint:none</additionalparam>

与

<doclint>none</doclint>