Where did the standard come from?

The plugin documentation standard was created to address frequent complaints about the lack of documentation, specifically on the Maven plugins. The standard was based on the suggestions made on the Maven dev mailing list with some refinements. It is a community consensus of the basic documentation a Maven plugin should have.

Maven Documentation Checker Plugin (aka. DocCK) was created at that time to help check plugin documentation, but it is now unmaintained.

Why do we need a documentation standard?

The standard is not a set of rules but a guide to help plugin developers document their plugins better, for the benefit of the users of the plugin. The standard also reminds plugin developers of important details that need to be documented to help speed up the adoption of the plugin.

Generated Documentation

It is recommended that you let Maven generate the basic information for the plugin to make sure that that the basic information is always accurate and synchronized with the plugin implementation.

Documentation is generated by running

mvn site

Like any Maven project, this will generate a site based on the information in the POM used by Maven Project Info Reports Plugin, src/site and other reporting plugins configured in the POM (like javadoc, jxr, or any other classical project report plugin).

In addition, the most important additional reporting plugin for a plugin is the Maven Plugin Report Plugin, which will generate the documentation for each plugin goal based on the Mojo annotations. But in order for the generated site to be usable, the required information should be available to the Maven Site Plugin.

POM Elements

Like any Maven project, Maven extracts the information from the POM to let Maven Project Info Reports Plugin generate the pages under "Project Information". The first step in good documentation is to have accurate and visible basic project information. Maven can provide this for the plugin as long as the information in the POM is complete, descriptive, and accurate.

Plugin Goals List and Configuration Parameters for each Goal

The Maven Plugin Report Plugin is responsible for generating the "Plugin Documentation" plugin-info.html page and one [goal]-mojo.html page for each goal.

It needs to be added to the <reporting> section, unless it is already inherited from a parent POM:

<project>
  [...]
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-plugin-report-plugin</artifactId>
        <version>3.15.2</version>
      </plugin>
    </plugins>
  </reporting>
  [...]  
</project>

The comments, annotations and plugin goals parameter names are extracted from the plugin source and rendered in the "Plugin Documentation" page. In order for the generated site to be useful, here are some guidelines for documenting your plugin.

• All @Parameter fields should have a descriptive comment, informative enough that a regular user can understand.

      [...]
      /**
       * Put something informative here that a regular user can understand.
       */
      @Parameter
      private boolean someparameter;
      [...]

• If a parameter is not just a simple Java type or a list of simple types, but a specific additional class, give a sample XML snippet showing the structure of objects that can be configured.

      [...]
      /**
       * A complex configuration
       * <pre>
       * &lt;complexparameter&gt;
       *   &lt;field1&gt;field 1 value&lt;/field1&gt;
       *   [...]
       * &lt;/complexparameter&gt
       * </pre>
       */
      @Parameter
      private MyComplexObject complexparameter;
      [...]

  The class does not need any specific annotation. @Parameter on the Mojo field is sufficient to inject a bean instance created from XML configuration.

  See, for example, requirementsHistories parameter documentation rendered from plugin source code and RequirementsHistory class,

• The class level comment should explain what the goal does.

  [...]
  /**
   * Everything here will show up on the top of the generated plugin info page.
   */
  @Mojo(name = "somegoal", defaultPhase = LifecyclePhase.COMPILE)
  public class ExampleMojo
      extends AbstractWarMojo
  {
      public void execute()
          throws MojoExecutionException, MojoFailureException
      {
  [...]

• The @Component and readonly parameters are not required to have any comments, but it's still a good practice to provide them.

Site Organization

Visibility of the information is also crucial. Uniform navigation links greatly improve the visibility of the documentation. The index page can help emphasize important sections and pages of the plugin documentation.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>2.1.0</version>
  </skin>

  <body>
    <menu name="Overview">
      <item name="Introduction" href="index.html"/>
      <item name="Goals" href="plugin-info.html"/>
      <item name="Usage" href="usage.html"/>
      <item name="FAQ" href="faq.html"/>
    </menu>

    <menu name="Examples">
      <item name="description1" href="examples/example-one.html"/>
      <item name="description2" href="examples/example-two.html"/>
    </menu>
  </body>
</project>

Recommended Configured Reports

There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and JXR.

• Maven Javadoc Plugin

  Javadocs provide documentation that makes it easier for developers to know how to use a particular class. Instead of reading and understanding the actual source code, the developer can use the Javadocs instead to lookup the class attributes and methods.

  To enable javadoc for your plugin add the following to your pom.xml

  <project>
    [...]
    <build>
      [...]
    </build>
    <reporting>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>3.12.0</version>
          <configuration>
            <minmemory>128m</minmemory>
            <maxmemory>512</maxmemory>
            ...
          </configuration>
        </plugin>
      </plugins>
      [...]
    </reporting>   
    [...]
  </project>

  Check the documentation about the plugin's javadoc:javadoc goal for the advanced configurations.

• Maven JXR Plugin

  The Maven JXR Plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding javadoc if javadoc is generated. The cross-reference is great for those who want to better understand the inner workings of the plugin.

  To enable source code cross-references, add the following to your pom.xml

  <project>
    [...]
    <build>
      [...]
    </build>
    <reporting>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-jxr-plugin</artifactId>
          <version>3.3.1</version>
        </plugin>
      </plugins>
    </reporting>
    [...]
  </project>

  Check the JXR configuration page for the possible configuration parameters.