经常问的问题

  1. Maven Javadoc 插件支持哪些 Javadoc 选项？
  2. 我在 pom.xml 的哪个位置配置 Javadoc 插件？
  3. 我将 Javadoc 资源（如 HTML 文件或图像）放在哪里？
  4. 如何准确地知道 Javadoc 命令行？
  5. 如何添加额外的 Javadoc 参数？
  6. 如何添加额外的 Javadoc 选项？
  7. 如何增加 Javadoc 堆大小？
  8. 如何添加代理支持？
  9. 如何减少输出？
  10. 如何删除测试 Javadocs 报告？
  11. 如何部署 Javadoc jar 文件？
  12. 如何在聚合模式下包含额外的源代码目录？
  13. 如何在标准 Doclet中使用<links/>选项？
  14. 如何将交叉引用链接添加到内部-外部项目？
  15. 在带有 Sun JDK 的 Windows 上，为什么javadoc:javadoc目标会由于sun.net.www.ParseUtil.decode()中的 IllegalArgumentException 而爆炸？
  16. <encoding/>、<docencoding/>和<charset/>参数的值是多少？
  17. 为什么在 Java 8 下使用链接时会出错？
Maven Javadoc 插件支持哪些 Javadoc 选项？

Sun 在 Javadoc 主页上提供的所有选项都包含在 Maven Javadoc 插件中。此插件支持 Javadoc 1.4、1.5 和 6.0 选项。 有关更多信息，请参阅 Javadoc 包摘要和Javadoc 插件文档。

[最佳]

我在 pom.xml 的哪个位置配置 Javadoc 插件？

与所有其他报告插件一样，Javadoc 插件位于 pom.xml 的<reporting/>部分。在这种情况下，您需要调用mvn site来运行报告。

您也可以在pom.xml 的<build/>标签中的<plugins/>或<pluginsManagement/>中 配置它。在这种情况下，您需要调用 mvn javadoc:javadoc来运行主报告。

重要说明：使用<reporting/>或<build/>元素具有不同的行为，有关更多信息，请参阅 使用 <reporting/> 标签 VS <build/> 标签 部分。

[最佳]

我将 Javadoc 资源（如 HTML 文件或图像）放在哪里？

所有 javadoc 资源，如 HTML 文件、图像都可以放在 ${basedir}/src/main/javadoc目录中。

有关更多信息，请参阅使用 Javadoc 资源。

[最佳]

如何准确地知道 Javadoc 命令行？

Javadoc 插件使用 参数 files调用 Javadoc 工具，即名为“options”、“packages”和“argfile”的文件（或 Jdk < 1.4 的“files”）： 

javadoc.exe(or .sh) @options @packages | @argfile

这些参数文件在运行时根据 Javadoc 插件配置生成，并在 Javadoc 插件结束时被删除。

要保留它们，只需在 Javadoc 插件配置中添加 <debug>true</debug> 或调用 mvn javadoc:javadoc -Ddebug=true或mvn javadoc:javadoc -X。在这种情况下，将在apidocs 目录中创建一个附加脚本文件（javadoc.bat（或 .sh）。

[最佳]

如何添加额外的 Javadoc 参数？

您可能需要添加更多Javadoc 参数以供Javadoc 工具处理（即用于doclet）。

为此，您应该在 Javadoc 插件配置中 使用<additionalOptions/>参数。

[最佳]

如何添加额外的 Javadoc 选项？

您可能需要添加更多 J 选项（即运行 Javadoc 工具（如 -J-Xss）的运行时系统 Java 选项）以由 Javadoc 工具处理。为此，您应该在 Javadoc 插件配置中 使用<additionalJOption/>参数。

Javadoc 插件使用 J 选项调用 Javadoc 工具，即： 

CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%

[最佳]

如何增加 Javadoc 堆大小？

如果需要增加 Javadoc 堆大小，则应在 Javadoc 插件配置中使用<minmemory/>和 <maxmemory/>参数。例如： 

set CLASSPATH=

注意：内存单元取决于所使用的 JVM。支持的单位可以是：k、 kb、m、mb、g、gb、t、 tb。如果未指定单位，则默认单位为m。

[最佳]

如何添加代理支持？

要在 Javadoc 工具中指定代理，您需要在 ${user.home}/.m2/settings.xml中配置一个活动代理，类似于： 

set CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip
这样，Javadoc 工具将使用网络 J 选项调用，即： 
${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
    -J-Dhttp.proxySet=true \
    -J-Dhttp.proxyHost=proxy.somewhere.com \
    -J-Dhttp.proxyPort=3128 \
    -J-Dhttp.nonProxyHosts="java.sun.com|*.somewhere.com" \
    -J-Dhttp.proxyUser="foo" \
    -J-Dhttp.proxyPassword="bar" \
    @options \
    @packages | @argfile

注意：如果您的代理需要更多 JVM 网络属性 （如 NTLM），您始终可以使用Javadoc 插件配置中 的<additionalJOption/>参数添加 JVM 选项，即：

<configuration>
  <additionalJOption>-J-Dhttp.auth.ntlm.domain=MYDOMAIN</additionalJOption>
  ...
</configuration>

[最佳]

如何减少输出？

只需在 Javadoc 插件配置 中将<quiet/>参数设置为true 。

[最佳]

如何删除测试 Javadocs 报告？

您需要配置<reportSets/>参数。阅读 选择性 Javadocs 报告部分以获取更多信息。

[最佳]

如何部署 Javadoc jar 文件？

基本上，您需要调用mvn clean javadoc:jar deploy。如果要在发布过程中包含 javadoc jar，则需要将其附加到发布配置文件中，例如： 

<project>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-javadocs</id>
                <goals>
                  <goal>jar</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
    ...
  </profiles>
  ...
</project>

要在给定的 Maven 存储库上部署 Javadoc jar，您可以调用： 

mvn deploy:deploy-file \
    -DgroupId=<group-id> \
    -DartifactId=<artifact-id> \
    -Dversion=<version> \
    -Dfile=<path-to-file> \
    -Dpackaging=jar \
    -DrepositoryId=<repository-id> \
    -Durl=dav:http://www.myrepository.com/m2 \
    -Dclassifier=javadoc

[最佳]

如何在聚合模式下包含额外的源代码目录？

如果在聚合模式下使用 Javadoc 报告，即使用聚合参数，并且如果 Javadoc 报告不包含使用 build-helper:add-source目标定义的附加源代码目录，则需要使用javadoc:aggregate目标而不是javadoc:javadoc目标。阅读 Aggregating Javadocs for Multi-Projects部分了解更多信息。

[最佳]

如何在标准 Doclet中使用<links/>选项？

您需要配置<links/>参数。此外，您应该在 Javadoc 中正确编写引用，即：

  • @see MyMojo或{@link MyMojo}将不起作用。
  • @see com.mycompany.plugin.myplugin.MyMojo或{@link com.mycompany.myplugin.MyMojo} 将起作用。

[最佳]

如何将交叉引用链接添加到内部-外部项目？

请参考链接配置页面。

[最佳]

在带有 Sun JDK 的 Windows 上，为什么javadoc:javadoc目标会由于sun.net.www.ParseUtil.decode()中的 IllegalArgumentException 而爆炸？

您在 Windows XP 上新安装了 Sun JDK 5 或 JDK 6，当您运行mvn javadoc:javadoc时，您会遇到这样的sun.net.www.ParseUtil.decode ()异常 。

How to add additional Javadoc parameters?

You could need to add more Javadoc parameters to be process by the Javadoc Tool (i.e. for doclet).

For this, you should use the <additionalOptions/> parameter in your Javadoc Plugin configuration.

[top]

How to add additional Javadoc options?

You could need to add more J options (i.e. runtime system java options that runs Javadoc tool like -J-Xss) to be process by the Javadoc Tool. For this, you should use the <additionalJOption/> parameter in your Javadoc Plugin configuration.

The Javadoc Plugin calls the Javadoc tool with J options, i.e.: 

CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%

[top]

How to increase Javadoc heap size?

If you need to increase the Javadoc heap size, you should use the <minmemory/> and <maxmemory/> parameters in your Javadoc Plugin configuration. For instance: 

set CLASSPATH=

Note: The memory unit depends on the JVM used. The units supported could be: k, kb, m, mb, g, gb, t, tb. If no unit specified, the default unit is m.

[top]

How to add proxy support?

To specify a proxy in the Javadoc tool, you need to configure an active proxy in your ${user.home}/.m2/settings.xml, similar to: 

set CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip
With this, the Javadoc tool will be called with networking J options, i.e.: 
${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
    -J-Dhttp.proxySet=true \
    -J-Dhttp.proxyHost=proxy.somewhere.com \
    -J-Dhttp.proxyPort=3128 \
    -J-Dhttp.nonProxyHosts="java.sun.com|*.somewhere.com" \
    -J-Dhttp.proxyUser="foo" \
    -J-Dhttp.proxyPassword="bar" \
    @options \
    @packages | @argfile

Note: If your proxy needs more JVM networking properties (like NTLM), you could always add JVM options using the <additionalJOption/> parameter in your Javadoc Plugin configuration, i.e.: 

<configuration>
  <additionalJOption>-J-Dhttp.auth.ntlm.domain=MYDOMAIN</additionalJOption>
  ...
</configuration>

[top]

How to have less output?

Just set the <quiet/> parameter to true in your Javadoc Plugin configuration.

[top]

How to remove test Javadocs report?

You need to configure the <reportSets/> parameter. Read the Selective Javadocs Reports part for more information.

[top]

How to deploy Javadoc jar file?

Basically, you need to call mvn clean javadoc:jar deploy. If you want to include the javadoc jar in a release process, you need to attach it in the release profile, for instance: 

<project>
  ...
  <profiles>
    <profile>
      <id>release</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-javadocs</id>
                <goals>
                  <goal>jar</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
    ...
  </profiles>
  ...
</project>

To deploy the Javadoc jar on a given Maven repository, you could call: 

mvn deploy:deploy-file \
    -DgroupId=<group-id> \
    -DartifactId=<artifact-id> \
    -Dversion=<version> \
    -Dfile=<path-to-file> \
    -Dpackaging=jar \
    -DrepositoryId=<repository-id> \
    -Durl=dav:http://www.myrepository.com/m2 \
    -Dclassifier=javadoc

[top]

How to include additional source code directories in aggregate mode?

If you use the Javadoc report in the aggregate mode, i.e. using the aggregate parameter, and if the Javadoc report does not include additional source code directories defined using the build-helper:add-source goal, you need to use the javadoc:aggregate goal instead of javadoc:javadoc goal. Read the Aggregating Javadocs for Multi-Projects part for more information.

[top]

How to use <links/> option in Standard Doclet?

You need to configure the <links/> parameter. Also, you should correctly write references in your Javadoc, i.e.:

  • @see MyMojo or {@link MyMojo} will NOT work.
  • @see com.mycompany.plugin.myplugin.MyMojo or {@link com.mycompany.myplugin.MyMojo} will work.

[top]

How to add cross reference link to internal-external projects?

Please refer to Links configuration page.

[top]

On Windows with Sun JDK, why javadoc:javadoc goal blows up due to an IllegalArgumentException in sun.net.www.ParseUtil.decode()?

You are on Windows XP with Sun JDK 5 or JDK 6 freshly installed, and when you run mvn javadoc:javadoc, you are stick by an sun.net.www.ParseUtil.decode() exception like this one.

Your CLASSPATH environement variable is probably corrupted, i.e. something like: 

CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%
with %JAVAHOME% not a valid environment variable.

To resolve it, just reset the CLASSPATH environement variable, i.e.: 

set CLASSPATH=
or set a new CLASSPATH environement variable, i.e.: 
set CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip
or fix the wrong environment variable.

Refer you to http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854 from Sun for more details.

[top]

What are the values of <encoding/>, <docencoding/> and <charset/> parameters?

By default, these parameters have the following values:

<encoding/>
Value of ${project.build.sourceEncoding} property or the value of the file.encoding system property if not specified.
<docencoding/>
Value of ${project.reporting.outputEncoding} property or UTF-8 if not specified.
<charset/>
Value of docencoding parameter if not specified.

[top]

Why do I get errors when using links under Java 8?

Due to a bug in JDK 8 you need at least Java 8u20 for this to work. See MJAVADOC-393 for more info.

[top]

.run(URLClassLoader.java:362) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findResource(URLClassLoader.java:359) at java.lang.ClassLoader.getResource(ClassLoader.java:977) at java.lang.ClassLoader.getResourceAsStream(ClassLoader.java:1159) at javax.xml.parsers.SecuritySupport.run(SecuritySupport.java:96) at java.security.AccessController.doPrivileged(Native Method) at javax.xml.parsers.SecuritySupport.getResourceAsStream(SecuritySupport.java:89) at javax.xml.parsers.FactoryFinder.findJarServiceProvider(FactoryFinder.java:250) at javax.xml.parsers.FactoryFinder.find(FactoryFinder.java:223) at javax.xml.parsers.SAXParserFactory.newInstance(SAXParserFactory.java:128) at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:72) at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108) at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) at com.sun.tools.javadoc.Start.begin(Start.java:128) at com.sun.tools.javadoc.Main.execute(Main.java:41) at com.sun.tools.javadoc.Main.main(Main.java:31) com.sun.tools.doclets.internal.toolkit.util.DocletAbortException at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:79) at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108) at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) at com.sun.tools.javadoc.Start.begin(Start.java:128) at com.sun.tools.javadoc.Main.execute(Main.java:41) at com.sun.tools.javadoc.Main.main(Main.java:31) com.sun.tools.doclets.internal.toolkit.util.DocletAbortException at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:159) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64) at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42) at com.sun.tools.doclets.standard.Standard.start(Standard.java:23) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215) at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91) at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340) at com.sun.tools.javadoc.Start.begin(Start.java:128) at com.sun.tools.javadoc.Main.execute(Main.java:41) at com.sun.tools.javadoc.Main.main(Main.java:31) Command line was:C:\Java\jdk1.6.0_03\jre\..\bin\javadoc.exe @options @packages ...

您的CLASSPATH环境变量可能已损坏，例如： 

CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%
%JAVAHOME%不是有效的环境变量 。

要解决它，只需重置CLASSPATH环境变量，即：

设置类路径=
或设置一个新的CLASSPATH环境变量，即： 
设置 CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip
或修复错误的环境变量。

有关详细信息，请参阅 Sun 的http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854 。

[最佳]

<encoding/>、<docencoding/>和<charset/>参数的值是多少？

默认情况下，这些参数具有以下值：

<编码/>
${project.build.sourceEncoding}属性的值或 file.encoding系统属性的值（如果未指定）。
<文档编码/>
${project.reporting.outputEncoding}属性的值或UTF-8（如果未指定）。
<字符集/>
如果未指定，则为docencoding参数的值。

[最佳]

为什么在 Java 8 下使用链接时会出错？

由于JDK 8 中的一个错误， 您至少需要 Java 8u20 才能使其工作。有关详细信息，请参阅 MJAVADOC-393 。

[最佳]