| ------ |
| Aggregating Javadocs for Multi-Projects |
| ------ |
| Maria Odea Ching |
| Vincent Siveton |
| ------ |
| 2009-08-04 |
| ------ |
| |
| ~~ 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 |
| |
| 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>${project.version}</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 {{{../javadoc-mojo.html#aggregate}\<aggregate/\>}} parameter doesn't include generate source directories defined |
| using the {{{http://mojo.codehaus.org/build-helper-maven-plugin/add-source-mojo.html}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-report.html}Selective Javadocs Reports page}}. |
| |
| +-----+ |
| <project> |
| ... |
| <build> |
| <plugins> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-javadoc-plugin</artifactId> |
| <version>${project.version}</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>${project.version}</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> |
| +-----+ |
| |
| The Javadoc plugin contains several <<<aggregate>>> goals to be use with an aggregator project. Here is the full list |
| of all <<<aggregate>>> goals: |
| |
| * {{{../aggregate-mojo.html}javadoc:aggregate}} to generate the Javadoc files. |
| |
| * {{{../test-aggregate-mojo.html}javadoc:test-aggregate}} to generate the test Javadoc files. |
| |
| * {{{../aggregate-jar-mojo.html}javadoc:aggregate-jar}} to create an archive file of the Javadoc files. |
| |
| * {{{../test-aggregate-jar-mojo.html}javadoc:test-aggregate-jar}} to create an archive file of the test Javadoc files. |
| |
| [] |