Configuring Javadoc aggregation in Maven

Question

I'm trying to create an aggregate Javadoc site for all the modules in my project, but I can't seem to configure the plugin in a way that is satisfactory. Mainly, I can't seem to get it to aggregate the javadocs all the while detecting links and excluding certain packages. Essentially, it appears the configuration of the plugin is ignored entirely.

I have a root pom.xml that refers to a bunch of submodules and contains the following configuration:

<modules>
    <module>foo</module>
    <module>bar</module>
</modules>
<build>
<plugins>
   <plugin>
       <groupId>org.maven.apache.plugins</groupId>
       <artifactId>maven-javadoc-plugin</artifactId>
       <version>2.9</version>
       <executions>
           <execution>
               <id>aggregate</id>
               <phase>site</phase>
               <goals>
                   <goal>aggregate</goal>
               </goals>
               <configuration>
                  <links>
                    <link>http://docs.oracle.com/javase/6/docs/api</link>
                    <link>http://static.netty.io/3.5/api</link>
                    <link>http://google-guice.googlecode.com/git/javadoc</link>
                    <link>http://docs.guava-libraries.googlecode.com/git-history/release/javadoc</link>
                    <link>http://fasterxml.github.com/jackson-databind/javadoc/2.0.4</link>
                    <link>https://developers.google.com/protocol-buffers/docs/reference/java</link>
                  </links>
                  <bootclasspath>${sun.boot.class.path}</bootclasspath>
                  <additionalJOption>-J-Xmx1024m</additionalJOption>
                  <detectJavaApiLink>true</detectJavaApiLink>
                  <detectLinks>true</detectLinks>
                  <excludePackageNames>*.testing.*</excludePackageNames>
               </configuration>
           </execution>
      </executions>
  </plugin>
</plugins>
</build>

But when I run mvn javadoc:aggregate with this setup, I end up with a javadoc site that has no links to any of the referenced libraries and still includes all the testing classes.

I don't even see the plugin attempting to download the package-list for each declared link source.

On the other hand, generating the javadoc for each individual module works well and as expected.

What am I getting wrong?

Answer 1

Plugin configurations can be placed on two levels; inside the execution tag or outside of it ("global").

When the configuration is inside the execution tag it belongs to that particular execution. In your case you will have to run mvn site for it to execute since it is bound to that phase.

When the mvn javadoc:aggregate command is used it looks for the "global" configuration. In your pom there is no such configuration and thus it uses the default configuration.

Change your plugin configuration to this instead:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <configuration>
        <links>
            <link>http://docs.oracle.com/javase/7/docs/api</link>
            <link>http://static.netty.io/3.5/api</link>
            <link>http://google-guice.googlecode.com/git/javadoc</link>
            <link>http://docs.guava-libraries.googlecode.com/git-history/release/javadoc</link>
            <link>http://fasterxml.github.com/jackson-databind/javadoc/2.0.4</link>
            <link>https://developers.google.com/protocol-buffers/docs/reference/java</link>
        </links>
        <bootclasspath>${sun.boot.class.path}</bootclasspath>
        <additionalJOption>-J-Xmx1024m</additionalJOption>
        <detectJavaApiLink>true</detectJavaApiLink>
        <detectLinks>true</detectLinks>
        <excludePackageNames>*.testing.*</excludePackageNames>
    </configuration>
    <executions>
        <execution>
            <id>aggregate</id>
            <phase>site</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You can place a configuration inside the execution part to override and specialize the configuration for that execution.

BTW The <groupId> is wrong in your pom. It should be

<groupId>org.apache.maven.plugins</groupId>

and not

<groupId>org.maven.apache.plugins</groupId>