Apache Maven Javadoc Plugin – Generating Test Javadocs

Generating Test Javadocs

Here is a typical project used by the Maven Javadoc plugin:

yourproject
  |-- src
     |-- main
     |  |-- java
     |  |  |-- org
     |  |     |-- apache
     |  |        |-- myapp
     |  |         `-- App.java
     |  |-- javadoc
     |   `-- overview.html
     |     |-- org
     |        |-- apache
     |           |-- myapp
     |            `-- package.html
     |              |-- doc-files
     |               `-- app.png
     |-- test
        |-- java
        |  |-- org
        |     |-- apache
        |        |-- myapp
        |         `-- AppTest.java
        |-- javadoc
         `-- overview.html
           |-- org
              |-- apache
                 |-- myapp
                  `-- package.html
                    |-- doc-files
                     `-- app.png

Using the javadoc:test-javadoc goal

You need to configure the Maven Javadoc plugin in your pom.xml, for instance:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.6.3</version>
        <configuration>
          <doctitle>My API for ${project.name} ${project.version}</doctitle> <!-- Used by javadoc:javadoc goal -->
          <windowtitle>My API for ${project.name} ${project.version}</windowtitle> <!-- Used by javadoc:javadoc goal -->

          <testDoctitle>My Test API for ${project.name} ${project.version}</testDoctitle> <!-- Used by javadoc:test-javadoc goal -->
          <testWindowtitle>My Test API for ${project.name} ${project.version}</testWindowtitle> <!-- Used by javadoc:test-javadoc goal -->
          ...
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>

You could call mvn javadoc:test-javadoc or mvn site. See javadoc:test-javadoc parameters for more informations.

Notes:

If you don't set <testDoctitle/> or <testWindowtitle/> parameters, the Test Javadoc report use the same configuration (i.e. <doctitle/> or <windowtitle/> parameters) that Javadoc report (backward compatible reasons).
To run the reports selectively, you need to include only the reports that you prefer. Read the Selective Javadocs Reports part for more information.
To allow the copy of resources, you need to add the <docfilessubdirs/> parameter. Read the Using Javadoc Resources page for more information.

Using the <reportSets/> configuration parameter

You could also want a different kind of configuration for the Javadoc report and the test Javadoc report. For this, you need to configure the Maven Javadoc plugin in your pom.xml to handle the <reportSets/> configuration parameter, for instance:

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.6.3</version>
        <reportSets>
          <reportSet>
            <id>html</id>
            <configuration>
              <doctitle>My API for ${project.name} ${project.version}</doctitle>
              <windowtitle>My API for ${project.name} ${project.version}</windowtitle>
              ...
            </configuration>
            <reports>
              <report>javadoc</report>
            </reports>
          </reportSet>
          <reportSet>
            <id>test-html</id>
            <configuration>
              <testDoctitle>My Test API for ${project.name} ${project.version}</testDoctitle>
              <testWindowtitle>My Test API for ${project.name} ${project.version}</testWindowtitle>
              ...
            </configuration>
            <reports>
              <report>test-javadoc</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

You need to call mvn site.