What are the Javadoc options supported by the Maven Javadoc Plugin?

All options provided by Sun on the Javadoc homepages are wrapped in the Maven Javadoc Plugin. This plugin supports Javadoc 1.4, 1.5 and 6.0 options. Refer you to the Javadoc Package Summary for more information and to the Javadoc Plugin Documentation.

[top]

Where in the pom.xml do I configure the Javadoc Plugin?

Like all other reporting plugins, the Javadoc Plugin goes in the <reporting/> section of your pom.xml. In this case, you will need to call mvn site to run reports.

You could also configure it in the <plugins/> or <pluginsManagement/> in <build/> tag of your pom.xml. In this case, you will need to call mvn javadoc:javadoc to run the main report.

IMPORTANT NOTE: using <reporting/> or <build/> elements have not the same behavior, refer to Using the <reporting/> Tag VS <build/> Tag part for more information.

[top]

Where do I put Javadoc resources like HTML files or images?

All javadoc resources like HTML files, images could be put in the ${basedir}/src/main/javadoc directory.

See Using Javadoc Resources for more information.

[top]

How to know exactly the Javadoc command line?

The Javadoc Plugin calls the Javadoc tool with argument files, i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk < 1.4):

${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
    @options \
    @packages | @argfile

These argument files are generated at runtime depending the Javadoc Plugin configuration and are deleted when the Javadoc Plugin ended.

To preserve them, just add <debug>true</debug> in your Javadoc Plugin configuration or just call mvn javadoc:javadoc -Ddebug=true or mvn javadoc:javadoc -X. In this case, an additional script file (javadoc.bat (or .sh) will be created in the apidocs directory.

[top]

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 <additionalparam/> 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.:

${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
    -J-Xss128m \
    @options \
    @packages | @argfile

[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:

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          ...
          <minmemory>128m</minmemory>
          <maxmemory>1g</maxmemory>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </reporting>
  ...
</project>

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:

<settings>
  ...
  <proxies>
   <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>3128</port>
      <username>foo</username>
      <password>bar</password>
      <nonProxyHosts>java.sun.com|*.somewhere.com</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>
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]