maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bentm...@apache.org
Subject svn commit: r647410 - /maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt
Date Sat, 12 Apr 2008 10:02:18 GMT
Author: bentmann
Date: Sat Apr 12 03:02:14 2008
New Revision: 647410

URL: http://svn.apache.org/viewvc?rev=647410&view=rev
Log:
o Polished site

Modified:
    maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt

Modified: maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt?rev=647410&r1=647409&r2=647410&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt (original)
+++ maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt Sat Apr
12 03:02:14 2008
@@ -11,9 +11,9 @@
 *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.   
+ 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?
  
@@ -23,7 +23,7 @@
  
 Generated Documentation 
 
- It is recommended that you let maven generate the basic information for the plugin to make
sure that
+ 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  
@@ -36,42 +36,42 @@
  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
+*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 
+ 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
+ Minimum elements for a valid POM:
 
- * modelVersion - POM model version, currently 4.0.0
+ * <<<\<modelVersion\>>>> - POM model version, currently 4.0.0
  
- * groupId - the package name
+ * <<<\<groupId\>>>> - the package name
  
- * artifactId - artifact name
+ * <<<\<artifactId\>>>> - artifact name
  
- * packaging - type of artifact produced by the POM
+ * <<<\<packaging\>>>> - type of artifact produced by the POM
 
- * version - the plugin version
+ * <<<\<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.
+ required by the users to effectively use the plugin:
 
- * name - plugin's name, <Maven NNN Plugin> for plugins hosted at the Maven project
or
+ * <<<\<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
+ * <<<\<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>
+ * <<<\<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
+ * <<<\<prerequisites\>>>> - the minimum version of Maven required
to use this plugin
   
- * issueManagement - describes the system used for reporting problems and modification requests
+ * <<<\<issueManagement\>>>> - describes the system used for reporting
problems and modification requests
  
 +--------------+
   [...]
@@ -82,9 +82,9 @@
   [...] 
 +--------------+
  
- * inceptionYear - year the plugin was first created
+ * <<<\<inceptionYear\>>>> - year the plugin was first created
  
- * mailingLists - lists where other users or the developers can be contacted for help and
discussions
+ * <<<\<mailingLists\>>>> - lists where other users or the developers
can be contacted for help and discussions
  
 +--------------+
   [...]
@@ -103,9 +103,21 @@
   [...] 
 +--------------+
  
- * licenses - plugin license
+ * <<<\<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\>>>> - the source code management configuration - a plugin
without this would raise suspicion, might not be OSS
  
 +--------------+
   [...]
@@ -117,7 +129,7 @@
   [...]
 +--------------+ 
  
- * organization - the organization maintaining the plugin, just in case we need someone to
blame
+ * <<<\<organization\>>>> - the organization maintaining the plugin,
just in case we need someone to blame
 
 +--------------+
   [...]
@@ -130,9 +142,9 @@
 
 *Plugin Configuration Parameters
 
- The plugin plugin is responsible for generating the Plugin Info site. The comments, annotations
and plugin parameter 
+ The Maven 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.
+ 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
  
@@ -168,17 +180,19 @@
 
  * the <<<@component>>> and <<<@readonly>>> parameters
are not required to have any comments but it's still a good practice to provide one
  
-*Site organization 
+*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 
+**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>
     <links>
       <item name="Maven 2" href="http://maven.apache.org/"/>
@@ -199,9 +213,10 @@
     <menu ref="reports"/>
     
   </body>
+</project>
 +--------------+    
   
-***Navigation links
+***Navigation Links
   
  * Introduction
  
@@ -246,23 +261,22 @@
  
  * Goals
   
-   <<<plugin-info.html>>> is generated by the plugin plugin. Until the
site plugin is updated it would be better to pull it out
+   <<<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
+   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
+   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"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <faqs id="FAQ" title="Frequently Asked Questions">
   <part id="General">
     <faq id="question">
@@ -284,15 +298,15 @@
   
    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-javadoc-plugin/}Maven Javadoc Plugin Examples}}
   
-  {{{http://maven.apache.org/plugins/maven-war-plugin/}Maven War Plugin Examples}}
+   * {{{http://maven.apache.org/plugins/maven-war-plugin/}Maven War Plugin Examples}}
   
 *Recommended Configured Reports
  
-  There are 2 recommended report plugin to enhance the plugin documentation, javadoc and
jxr.
+  There are 2 recommended report plugins to enhance the plugin documentation, Javadoc and
JXR.
   
-  * Javadoc Report Plugin
+  * 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.
@@ -309,7 +323,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
-        <version>2.2</version>
+        <version>2.4</version>
         <configuration>
           <minmemory>128m</minmemory>
           <maxmemory>512</maxmemory>
@@ -322,15 +336,15 @@
   [...]
 +--------------+   
   
-  Check the {{{http://maven.apache.org/plugins/maven-javadoc-plugin/configuration.html}javadoc
documentation}} for the advanced configurations.
+  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.
   
-  * JXR Report Plugin
+  * Maven JXR Plugin
   
-  The JXR plugin generates a cross-reference of the project sources. The generated cross-references
are also linked to the corresponding
+  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 the JXR plugin add the following to your <<<pom.xml>>>
+  To enable source code cross-references add the following to your <<<pom.xml>>>
   
 +--------------+ 
   [...]



Mime
View raw message