You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by be...@apache.org on 2008/04/12 12:02:18 UTC
svn commit: r647410 -
/maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt
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>>>
+--------------+
[...]