Aggregating Javadocs For Multi-Projects
For example, consider the following directory structure:
Project |-- pom.xml |-- Module1 | `-- pom.xml | `-- Module 2 | `-- pom.xml | `-- Module 3 | `-- pom.xml |-- Module4 | `-- pom.xml `-- Module5 `-- pom.xml
Since 3.1.0 the aggregate
has changed a little bit. It'll generate aggregated reports at every level. To get only an aggregated project at root level, you need to configure the pom like:
<project> ... <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.6.2</version> <reportSets> <reportSet> <id>aggregate</id> <inherited>false</inherited> <reports> <report>aggregate</report> </reports> </reportSet> <reportSet> <id>default</id> <reports> <report>javadoc</report> </reports> </reportSet> </reportSets> </plugin> </plugins> ... </reporting> ... </project>
Using The aggregate
Goals
The <aggregate/> parameter doesn't include generate source directories defined using the build-helper:add-source. In this case, you need to use the aggregate
goal and test-aggregate
goals. You could define these goals in the <build/> element (using the <execution/> tag) or <reporting/> element (using the <reportSet/> tag) as shown below. For more information, refer to the Selective Javadocs Reports page.
<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.6.2</version> <configuration> <!-- Default configuration for all reports --> ... </configuration> <executions> <execution> <id>aggregate</id> <goals> <goal>aggregate</goal> </goals> <phase>site</phase> <configuration> <!-- Specific configuration for the aggregate report --> ... </configuration> </execution> ... </executions> </plugin> ... </plugins> </build> ... </project>
<project> ... <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>3.6.2</version> <configuration> <!-- Default configuration for all reports --> ... </configuration> <reportSets> <reportSet> <id>non-aggregate</id> <configuration> <!-- Specific configuration for the non aggregate report --> ... </configuration> <reports> <report>javadoc</report> </reports> </reportSet> <reportSet> <id>aggregate</id> <configuration> <!-- Specific configuration for the aggregate report --> ... </configuration> <reports> <report>aggregate</report> </reports> </reportSet> ... </reportSets> </plugin> ... </plugins> </reporting> ... </project>
Aggregating Javadocs For Modularized projects
Since Java 9 it is possible to add module descriptors to your projects, which can have an impact on the generated reports. Be aware that is not possible to have a mixture of named and unnamed modules. Ideally every Maven module has a Java module descriptor, but this is not always possible, e.g. due to split packages of dependencies. In such case you must have a jar containing a META-INF/MANIFEST.MF
with an entry for the Automatic-Module-Name
. In other words: ensure to call package javadoc:aggregate
, because the manifest file is only being read from jar, not from folder.
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <configuration> <archive> <manifestEntries> <Automatic-Module-Name>com.foo.bar</Automatic-Module-Name> </manifestEntries> </archive> </configuration> </plugin>
Occasionally, automatic modules need to import named modules. For example,
error: package org.w3c.dom is not visible (package org.w3c.dom is declared in module java.xml, but module foobar does not read it)
can be solved by adding the relevant --add-modules options to the plugin configuration:
<additionalOptions> <option>--add-modules</option> <option>java.xml</option> </additionalOptions>
The Javadoc plugin contains several aggregate
goals to be use with an aggregator project. Here is the full list of all aggregate
goals:
- javadoc:aggregate to generate the Javadoc files.
- javadoc:test-aggregate to generate the test Javadoc files.
- javadoc:aggregate-jar to create an archive file of the Javadoc files.
- javadoc:test-aggregate-jar to create an archive file of the test Javadoc files.