Guide to the Plugin Documentation Standard – Maven (original) (raw)

Introduction

Where did the standard come 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

It will generate a plugin site based on the information in the POM, src/site and other reporting plugins configured in the POM. The most important reporting 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

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
• <groupId> - the package name
• <artifactId> - artifact name
• <packaging> - type of artifact produced by the POM
• <version> - the plugin version

Optional Elements

These 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, Maven NNN Plugin for plugins hosted at the Maven project or NNN Maven Plugin for all others
• <description> - project description, an overview of what the plugin can do
• <url> - the site of the plugin, normally maven.apache.org or org.mojohaus
• <prerequisites> - the minimum version of Maven required to use this plugin
• <issueManagement> - describes the system used for reporting problems and modification requests

<project>  
  [...]  
  <issueManagement>  
    <system>github</system>  
    <url>http://gitub.com/apache/foo/issues</url>  
  </issueManagement>  
  [...]  
</project>  

• <inceptionYear> - year the plugin was first created
• <mailingLists> - lists where other users or the developers can be contacted for help and discussions

<project>  
  [...]  
  <mailingLists>  
    <mailingList>  
      <name>Project users</name>  
      <post>announce@noonecares.com</post>  
      <subscribe>users-subscribe@noonecares.com</subscribe>  
      <unsubscribe>users-unsubscribe@noonecares.com</unsubscribe>  
      <archive>http://noonecares.archive.org</archive>  
    </mailingList>  
    <mailingList>  
      [...]  
    </mailingList>  
  </mailingLists>  
  [...]  
</project>  

• <licenses> - plugin license

<project>  
  [...]  
  <licenses>  
    <license>  
      <name>Apache License, Version 2.0</name>  
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>  
      <distribution>repo</distribution>  
    </license>  
  </licenses>  
  [...]  
</project>  

• <scm> - the source code management configuration - a plugin without this would raise suspicion, might not be OSS

<project>  
  [...]  
  <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/viewvc/some/project/trunk/</url>  
  </scm>  
  [...]  
</project>  

• <organization> - the organization maintaining the plugin, just in case we need someone to blame

<project>  
  [...]  
  <organization>  
    <name>Noone Care Software Foundation</name>  
    <url>http://noonecare.org/</url>  
  </organization>  
  [...]  
</project>  

Plugin Configuration Parameters

The Maven Plugin Plugin is responsible for generating the Plugin Info site and 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.1</version>
      </plugin>
    </plugins>
  </reporting>
  [...]  
</project>

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 are some guidelines you can follow when documenting your plugin.

• all @Parameter fields 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.  
 */  
@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 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 the layout of the page. It can be found in src/site/site.xml.

You must define a skin, if you are using a site descriptor. There is no default skin applied automatically.

Below is the suggested site descriptor template (with maven-fluido-skin).

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

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

YYYY-MM-DD

Plugin Name
Plugin introduction, description, and other relevant information.

• Goals Overview
  General information about the goals.
  • {{{.html}prefix:goal}} short description for this plugin goal.
• Usage
  General instructions on how to use the Plugin Name can be found on the {{{usage.html}usage page}}. Some more
  specific use cases are described in the examples given below. Last but not least, users occasionally contribute
  additional examples, tips or errata to the plugin's wiki page.
  In case you still have questions regarding the plugin's usage, please have a look at the {{{faq.html}FAQ}} and feel
  free to contact the {{{mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
  already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
  the {{{mailing-lists.html}mail archive}}.
  If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our
  {{{issue-management.html}issue management system}}. When creating a new issue, please provide a comprehensive description of your
  concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason,
  entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
  Of course, patches are welcome, too. Contributors can check out the project from our
  {{{scm.html}source repository}} and will find supplementary information in the
  {{{/guides/development/guide-helping.html}guide to helping with Maven}}.
• 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 Maven Plugin Plugin. Until the Maven 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 (this was previously called 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 which are usually located in src/site/fml/faq.fml. The example below provides a template for your FAQ:

<?xml version="1.0" encoding="UTF-8"?>  
<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 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.11.2</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-references is great for those who wants 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.