Introduction

Where did the standard came from?

The plugin documentation standard was created to address the frequent complain of 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 what basic documentation a maven plugin should have.

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 the plugin developers of the important details that needs 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:site

It will generate a plugin site based on the information in the POM, src/site and other reporting plugins configured in the POM. But in order for the generated site to be usable, the required information should be available to the site plugin.

POM elements

Maven extracts the information from the POM to generate the pages under Project Information. The first step in having a good documentation is to have an 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.

Required Elements

Minimum Elements for a valid pom

  • modelVersion - POM model version, currently 4.0.0
  • version - the plugin version
  • groupId - the package name
  • artifactId - artifact name
  • packaging - type of artifact produced by the POM

Optional Elements

This might be optional elements in a valid POM but they are important basic project information required by the users to effectively use the plugin.

  • name - plugin's name
  • description - project description, an overview of what the plugin can do
  • url - the site of the plugin, normally maven.apache.org or mojo.codehaus.org
  • issueManagement - describes the system used for reporting problems and modification requests
     [...]
    <issueManagement>
       <system>jira</system>
       <url>http://jira.someproject.org</url>
    </issueManagement>    
 [...]
  • prerequisites - would have an initial value of maven, list of descriptive name of dependencies.
  • inceptionYear - year the plugin was made
  • mailingLists - list where the developers can be contacted for problems and modification requests
     [...]
    <mailingLists>
        <mailingList>
           <name>Project issues</name>
           <post>announce@noonecares.com</post>
           <subscribe>issues-subscribe@noonecares.com</subscribe>
           <unsubscribe>issue-unsubscribe@noonecares.com</unsubscribe>
           <archive>http://noonecares.archive.org</archive>
        </mailingList>    
        <mailingList>
        [...]
        <mailingList>
    </mailingLists>    
 [...]
  • license - plugin license
  • scm - the source code management configuration. A plugin without this would raise suspicion, might not be OSS.
     [...]
    <scm>
       <connection>scm:svn:http://noonecares.com/some/plugin/project/trunk</connection>
       <developerConnection>scm:svn:https://noonecares.com/some/plugin/project/trunk</developerConnection>
       <url>http://noonecares.com/viewcvs.cgi/some/project/trunk/</url>
    </scm>
 [...]
  • organization - the organization maintaining the plugin, just in case we need someone to blame.
     [...]
  <organization>
    <name>Noone Care Software Foundation</name>
    <url>http://noonecare.org/</url>
  </organization> 
 [...]

Plugin Configuration Parameters

The plugin plugin is responsible for generating the Plugin Info site. The comments, annotations and plugin parameter names are extracted from the plugin source and rendered in the Plugin Info page. In order for the generated site to be useful here's some guidelines you can follow when documenting your plugin.

  • all @parameter field should have a descriptive comment, informative enough that even a regular user can understand. 
     [...]
    /**
     *  put something informative here that a regular user can understand
     * 
     * @parameter 
     */
    private boolean someparameter;
 [...]
  • class level comment should explain what the goal does.
    [...]
/**
 * Everything here will show up on the top of the generated plugin info page
 *
 * @goal somegoal
 * @phase compile
 */
public class ExampleMojo
    extends AbstractWarMojo
{
    public void execute()
        throws MojoExecutionException, MojoFailureException
    {  
[...]
  • all @component and @readonly parameters are not required to have any comments but it's still a good practice to provide one.

Site organization

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

Site descriptor

The site descriptor describes the navigation links and can be found in src/site/site.xml. Below is the suggested site descriptor template.

  <body>
    <links>
      <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
    </links>

    <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>

    ${reports}
    
  </body>
Navigation links
  • Introduction

    The introduction is the front page of the plugin documentation. This is a good place to place any section and pages that needs to be emphasized. It is also suggested that the generated plugin parameter configuration be linked here. Below is the suggested src/site/apt/index.apt template

     ------
 Introduction
 ------
 Author
 ------
 DD MMMM YYYY
 ------


Plugin Name

  Plugin introduction, description, and other relevant information.

* Goals Overview

  General Information about the goals.

  * {{{<goal>.html}prefix:goal}} short description for this plugin goal.

* Usage

  Instructions on how to use the Plugin Name can be found {{{usage.html}here}}.

* Examples

  To provide you with better understanding of some usages of the Plugin Name,
  you can take a look into the following examples:

  * {{{examples/example-one.html}Example Description One}}

  * {{{examples/example-two.html}Example Description Two}}
  • Goals

    plugin-info.html is generated by the plugin plugin. Until the site plugin is updated it would be better to pull it out to the main menu for greater visibility. This contains the goals and their descriptions with a link to the configuration parameters. The information is based on the comments and annotations of the plugin.

  • Usage (Howto)

    The usage page describes the the basic use cases for the plugin goals which includes sample pom configurations and explanation of how the goals work.

  • FAQ

    A well documented project always collates frequently asked questions, so here it is.

    faq.fml template

      <?xml version="1.0"?>
  <faqs id="FAQ" title="Frequently Asked Questions">
   <part id="General">
     <faq id="question">
       <question>Question?</question>
       <answer>
         <p>
         Answer
         </p>
       </answer>
     </faq>
   </part>
  </faqs>
  • Examples

    The advanced configurations and examples not covered in the usage page is located here. Advanced users who wants to maximize the use of a plugin can check the items here. Tips on how to use the plugin effectively is also a good thing to put here.

    For examples of items under "Examples" check these plugin sites :

    Maven Javadoc Plugin Examples

    Maven War Plugin Examples

Recommended Configured Reports

There are 2 recommended report plugin to enhance the plugin documentation, javadoc and jxr.

  • Javadoc Report 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

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

    Check the javadoc documentation for the advanced configurations.

  • JXR Report Plugin

    The 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-references is great for those who wants to better understand the inner workings of the plugin.

    To enable the jxr plugin add the following to your pom.xml

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

    Check the jxr configuration page for the possible configuration parameters.