logo标签列表

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

javamavenmigrationjava-8javadoc
346

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

然而，自从我迁移到Java 8（1.8.0-ea-b90）以来，当我尝试构建或安装Javadoc不是“完美”的项目时，Maven绝对严格要求存在缺失文档标签，并显示许多与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] ^

这是我POM中配置Javadoc Maven插件的方法：

<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 7，一切都运行良好。也许这与在Java 8中运行的Maven有关的一个错误吗？我该怎么办才能让它工作（即能够构建项目的Javadoc并将其代码安装在我的本地仓库中）？ 我已经在OSX上测试了Maven 3.0.3和3.0.5。

更新：

如果我使用<failOnError>false</failOnError>更改我的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 仍未生成。

我在控制台看到的输出片段如下:

[ERROR] MavenReportException: Error while creating archive: Exit code: 1 - /Users/....java:18: warning: no @param ... Command line was: /Library/Java/Home/bin/javadoc @options @packages

Refer to the generated Javadoc files in '/Users/sergioc/Documents/workspaces/heal/minitoolbox/target/apidocs' dir.

at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeJavadocCommandLine(AbstractJavadocMojo.java:5043) at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeReport(AbstractJavadocMojo.java:1990) at org.apache.maven.plugin.javadoc.JavadocJar.execute(JavadocJar.java:181) at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:101) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:209) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:84) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:59) at org.apache.maven.lifecycle.internal.LifecycleStarter.singleThreadedBuild(LifecycleStarter.java:183) at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:161) at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:320) at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:156) at org.apache.maven.cli.MavenCli.execute(MavenCli.java:537) at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:196) at org.apache.maven.cli.MavenCli.main(MavenCli.java:141) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:491) at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:290) at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:230) at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:409) at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:352)

有没有解决方案可以在一步中构建源代码，安装项目并生成 Javadoc JAR，就像在 Java 7 中那样？

嗨@75inchpianist，我已经更新了问题，实际上它们是错误（尽管令人惊讶的是，错误的最后一行提到了一个警告，正如您在生成的输出中所看到的）。该项目未安装在我的本地存储库中，因此它不被视为简单的警告:( - Sergio
对于GoogleJuice：我遇到了错误“error: bad use of '>'”，因为我在JavaDoc注释中有一个大箭头。 - Drew Stephens
3
或许对某些人会有用：你可以通过在IntelliJ中运行检查Ctrl+Alt+Shift+i来轻松找到所有这些不完整的标签，其中包括“声明具有JavaDoc问题”。 - Sergey Ponomarev
1
这不是Maven，而是Javadoc程序，在Java 8中变得更加严格了。 - Thorbjørn Ravn Andersen
19个回答
425

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

DocLint是Java 8中的一项新功能，它的总结如下：

提供一种检测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>
19
有没有办法让这个在JDK 7上无法工作的程序也能在JDK 8上运行？因为它的 javadoc 不认识这个选项，所以在 JDK 7 上会失败。 - Feuermurmel
顺便说一下，Xdoclint参数可以配置得更加灵活。例如，要禁用令人烦恼的HTML检查，只需使用-Xdoclint:-html即可。 - turbanoff
9
虽然这回答了这里问的问题，但我想建议未来的访问者首先检查peterh的答案：https://dev59.com/LWUo5IYBdhLWcg3woAuu#34809831（大多数遇到此问题的人只需要修复少量地方，所以最好修复它们而不是禁用检查！） - Dave
9
对于maven-javadoc-plugin插件，请使用<doclint>none</doclint>。参见 https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#doclint - t7tran
11
自 Maven Javadoc 插件 3.0.0 起，<additionalparam/> 已被 <additionalOptions/> 替代。请参阅 https://issues.apache.org/jira/browse/MJAVADOC-475。 - fdelsert
显示剩余3条评论
102

在构建过程中，与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>
1
最佳解决方案可能是你的解决方案和Zapp在下面提供的方案之间的混合。如果您保持这种方式，mvn site:site命令仍将崩溃。您应该创建一个由1.8 jdk激活的配置文件，设置全局属性。 - Max Nad
66

这是我所知道的忽略 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/OpenJDK 6、7、8和11上进行了测试。

1
@clearlight，build和profiles都是Maven pom.xml中的顶层块。https://maven.apache.org/pom.html#Build。 - Oliver Gondža
45

适用于任何Java版本的最短解决方案：

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

只需将其添加到您的POM中，然后您就可以开始了。

这基本上是@ankon的答案加上@zapp的答案。

对于maven-javadoc-plugin 3.0.0用户：

请用<doclint>none</doclint>替换<additionalparam>-Xdoclint:none</additionalparam>

这对我来说是最好的解决方案。它适用于机器人Java 7和Java 8。但它的工作方式有点像魔法：如何将“additionalParam”参数添加到插件javadoc中（而不是其他文档）？ - pdem
1
@pdem 额外的参数添加到Maven中，而不是Javadoc插件。无论您是否明确使用该插件，此解决方案都有效。 - Fred Porciúncula
3
自从maven-javadoc-plugin 3.0.0版本以后，你需要在<properties>标签中添加<additionalJOption>-Xdoclint:none</additionalJOption>或<doclint>none</doclint>属性。 - Sergi
1
请问您能否澄清一下：在使用maven-javadoc-plugin 3.0.0及以上版本时，如果我只是简单地指定<doclint>none</doclint>（没有基于JDK版本的激活），它是否仍会在低于1.8的JDK上失败，或者maven-javadoc-plugin是否会自动检测当前Java版本是否支持doclint选项？ - Garret Wilson
38

将以下内容添加到pom文件的全局属性部分：

<project>
    ...
    <properties>
        <additionalparam>-Xdoclint:none</additionalparam>
    </properties>

其他回答中提供的常见解决方案（在插件部分添加该属性）由于某种原因未能起作用。只有通过全局设置才能成功构建javadoc jar。

2
这是唯一对我有效的解决方案。我也在这里阅读了答案：http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html - acvcu
34

我认为仅仅关闭DocLint不是一个好的解决方案，至少从长远来看不是。很好，Javadoc变得更加严格了，所以解决构建问题的正确方法是修复潜在问题。是的，你最终需要修复那些源代码文件。

以下是以前可能能够逃脱的要注意的事项：

  • 格式不正确的HTML（例如缺少结束标记、未转义的尖括号等）
  • 无效的{@link }（同样适用于类似的标签，如@see）
  • 不合法的@author值。这曾经被接受：@author John <john.doe@mine.com>，但由于未转义的尖括号而不再接受。
  • Javadoc中的HTML表格现在需要摘要或标题。有关说明，请参见此问题。

你只需修复源代码文件并持续构建你的Javadoc，直到可以成功构建为止。这很麻烦，但个人而言，当我将我的项目提升到DocLint级别时，我会更有信心我生成的Javadoc实际上就是我想要的。

当然，如果你正在生成Javadoc用于一些你没有编写的源代码，例如来自某个代码生成器，比如wsimport。奇怪的是，在实际发布JDK8之前，Oracle并没有为其自己的工具做好JDK8兼容性准备。看起来直到Java 9才会修复。只有在这种特殊情况下，我建议按照此页面其他地方记录的文档关闭DocLint。

1
完全同意这里的观点，不过对于生成的代码，您可以通过在javadoc插件的配置部分中添加一个excludePackageNames部分来告诉插件不处理给定包中的代码。请参见https://maven.apache.org/plugins/maven-javadoc-plugin/examples/exclude-package-names.html。 - Newtopian
1
这说起来比做起来容易得多，因为我们中的许多人遇到这些问题时都试图构建不熟悉的开源代码，其中某个地方有一个Maven依赖项，我们不知道它是如何工作的，因此没有简单的方法来解决根本原因。对于上下文存在太多的近视眼。人们需要更广泛地概括答案的范围，并提供更多关于如何进行修复的具体信息。 - clearlight
javadoc: error - 解码百分号编码字符时出错。我还没有找到任何解决javadoc的方法（没有迹象表明问题出现在一个小而简单的内部库中，我不知道它是否是maven依赖项）。mvn javadoc:fix对我的文件进行了许多添加，但没有解决根本问题。我将不得不禁用doclint才能使mvn release:perform正常工作。 - Skystrider
我使用了mvn clean -Darguments="-Dmaven.javadoc.skip=true" release:perform。 - Skystrider
31

仅覆盖 maven-javadoc-plugin 配置并不能解决 mvn site（例如在发布阶段使用）的问题。这是我需要做的：

<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>
      <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>-Xdoclint:none</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>
3
在网站插件激活时缺少此设置会导致 release:perform 失败，而 release:prepare 工作正常。这是一个重要的问题，如果没有解决，可能会让人很烦恼。 - Peter N. Steinmetz
请注意，对于最新版本的Maven 3，不建议通过maven-site-plugin的<reportPlugins>部分配置maven-javadoc-plugin。 - Martin Höller
我使用了mvn clean -Darguments="-Dmaven.javadoc.skip=true" release:perform。 - Skystrider
28

您可以尝试设置failOnError属性(请参见插件文档)为false：

<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>
              <failOnError>false</failOnError>
            </configuration>
        </execution>
    </executions>
</plugin>

如您从文档中所见，缺省值为true。

感谢 @Martin 的建议。有了那个属性，我至少可以重新构建和安装项目，但是我仍然缺少 Java 文档 jar 包（我需要它来部署到 Maven 中央库）。我已经在我的问题中更新了实验的细节。 - Sergio
这对我来说是最充分的答案。我只是想在Javadocs仍然不完整的情况下测试正在进行的开发构建。 - ZachSand
18

由于运行Maven命令所使用的JRE版本不同，您可能不希望在pom.xml中默认禁用DocLint。

因此，您可以从命令行使用开关-Dadditionalparam=-Xdoclint:none。

例如：mvn clean install -Dadditionalparam=-Xdoclint:none

3
这个特别有用，因为你也可以在 Jenkins 中使用它。将“全局 MAVEN_OPTS”（在“配置系统”下）设置为“-Dadditionalparam=-Xdoclint:none”，那么所有的构建都能够与 Java 8 一起工作。 - Wilfred Hughes
mvn org.apache.maven.plugins:maven-javadoc-plugin:3.1.0:jar -DadditionalJOption=-Xdoclint:none - 对我有效 - Roman Khomyshynets
11

在最新版本的maven-javadoc-plugin 3.0.0中，配置属性名称已更改。

因此，<additionalparam>将不起作用。所以我们必须按以下方式进行修改。

   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.0.0</version>
      <configuration>
         <doclint>none</doclint>
      </configuration>
  </plugin>
请查看此处的 doclint 文档：http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#doclint - Peter W
在2019年2月份，我通过从Github源代码构建OpenGrok来解决了这个问题。需要注意的是你的补丁需要放在项目的src/build目录下的pom.xml中。在我的情况下，我只需要搜索maven-javadoc-plugin，然后进入已经存在的<configuration></configuration>块并添加<doclint>none</doclint>。一旦掌握了这些知识，这一切都变得非常容易。在此情境下，我试图修复OpenGrok中的另一个错误，并且之前从未使用过Maven，不想递归到另一个子项目中去弄清楚如何应用快速修复方法。 - clearlight
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接