src/site/apt/guides/development/guide-plugin-documentation.apt

 ------
 Guide to the Plugin Documentation Standard
 ------
 Maven Team
 ------
 6 July 2006
 ------

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

 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
 {{{http://maven.apache.org/plugins/maven-plugin-plugin/}Maven Plugin 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 <mojo.codehaus.org>
 
 * <<<\<prerequisites\>>>> - the minimum version of Maven required to use this plugin
  
 * <<<\<issueManagement\>>>> - describes the system used for reporting problems and modification requests
 
+--------------+
  [...]
  <issueManagement>
    <system>jira</system>
    <url>http://jira.someproject.org</url>
  </issueManagement>    
  [...] 
+--------------+
 
 * <<<\<inceptionYear\>>>> - year the plugin was first created
 
 * <<<\<mailingLists\>>>> - lists where other users or the developers can be contacted for help and discussions
 
+--------------+
  [...]
  <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>    
  [...] 
+--------------+
 
 * <<<\<licenses\>>>> - plugin license

+--------------+
  [...]
  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  [...]
+--------------+ 
 
 * <<<\<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/viewvc/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 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:

+--------------+ 
  [...]
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-plugin-plugin</artifactId>
        <version>2.5.1</version>
      </plugin>
    </plugins>
  </reporting>    
  [...]  
+--------------+   
 
 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.
 *
 * @goal somegoal
 * @phase 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 can be found in <<<src/site/site.xml>>>. Below is the suggested site 
 descriptor template.
 
+--------------+  
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <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.

  * {{{<goal>.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
  {{{http://docs.codehaus.org/display/MAVENUSER/Plugin+Name}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 {{{mail-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 {{{mail-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-tracking.html}issue tracker}}. 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
  {{{source-repository.html}source repository}} and will find supplementary information in the
  {{{http://maven.apache.org/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:
  
   * {{{http://maven.apache.org/plugins/maven-javadoc-plugin/}Maven Javadoc Plugin Examples}}
  
   * {{{http://maven.apache.org/plugins/maven-war-plugin/}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>>>
  
+--------------+ 
  [...]
  <build>
    [...]
  </build>
  <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>
    </plugins>
    [...]
  </reporting>   
  [...]
+--------------+   
  
  Check the documentation about the plugin's {{{http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html}<<<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>>>
  
+--------------+ 
  [...]
  <build>
    [...]
  </build>
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jxr-plugin</artifactId>
        <version>2.1</version>
      </plugin>
    </plugins>
  </reporting>    
  [...]  
+--------------+   
  
  Check the {{{http://maven.apache.org/plugins/maven-jxr-plugin/jxr-mojo.html}JXR configuration page}} for the possible configuration parameters.