------
 Generating Test Javadocs
 ------
 Vincent Siveton
 ------
 2008-07-28
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Generating Test Javadocs

 There are two ways to generate the test javadocs in the Maven Javadoc plugin:

   * using the javadoc:test-javadoc goal

   * using the \<reportSets/\> configuration parameter

 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>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.5</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>
  </reporting>
  ...
</project>
+-----+

 You could call <mvn javadoc:test-javadoc> or <mvn site>. See
 {{{../test-javadoc-mojo.html}javadoc:test-javadoc parameters}} for more informations.

 <<Note>>: 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).

 <<Note>>: To run the reports selectively, you need to include only the reports that you prefer.
  Read the {{{selective-javadocs-report.html}Selective Javadocs Reports}} part 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>2.5</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>.