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>>>
+--------------+
[...]
