It is not an exaggeration when it's said that Apache Maven is being used by hundreds and thousands of developers, if not more, everyday.
In addition, Apache Maven has a thriving community and hundreds of individuals, groups, and teams that contribute to Apache Maven in the form of plugins.
However, a common complaint in the Apache Maven community discussions has been the lack of sufficient documentation, especially for Apache Maven plugins.
Thus the Apache Maven community recommends a set of plugin documentation guidelines for plugin developers.
Adhering to these guidelines helps plugin users and thus, in turn, fuels the greater adoption of the plugin.
For this recipe, you need to have an existing Apache Maven plugin project.
In addition, you should also be familiar with the Apache Maven site plugin and the overall reporting/documentation process in an Apache Maven project.
- Add the Maven plugin to the
reportingelement of the project POM filepom.xml, as shown in the following code:<reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-plugin-plugin</artifactId> <version>2.5.1</version> </plugin> </plugins> </reporting>Documentation for an Apache Maven plugin project can be automatically generated. The command for doing so is as follows:
$ mvn site - Verify that plugin documentation adheres to the Maven community standards by running the command:
$ mvn docck:check
The mvn site command will automatically generate a plugin site for your plugin project based on available information in the project POM file, the src/site folder, and available reporting plugins.
The Maven plugin is an important reporting plugin as it leads to the generation of documentation for each MOJO and thus for each plugin goal.
The first step for ensuring good documentation is to achieve completeness of the project's POM file. Make sure all optional elements in the project object model are filled in including organization details, names, descriptions, URLs, mailing lists, licenses, issue/bug trackers, source code repositories, and so on.
Additional recommended reporting plugins for your Maven plugin project are:
- Maven Javadoc plugin
- Maven JXR plugin
The following example shows how both can be included in your pom.xml file in the reporting element:
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.4</version>
<configuration>
<minmemory>128m</minmemory>
<maxmemory>512</maxmemory>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<version>2.1</version>
</plugin>
</plugins>
</reporting>