You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by de...@apache.org on 2007/07/23 14:28:34 UTC
svn commit: r558699 -
/maven/site/trunk/src/site/apt/guides/development/guide-plugin-documentation.apt
Author: dennisl
Date: Mon Jul 23 05:28:32 2007
New Revision: 558699
URL: http://svn.apache.org/viewvc?view=rev&rev=558699
Log:
o Add info on the naming of a plugin.
o Use the new way of referencing a menu in the site descriptor.
o Fix a couple of typos.
o Add some more formating.
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?view=diff&rev=558699&r1=558698&r2=558699
==============================================================================
--- 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 Mon Jul 23 05:28:32 2007
@@ -29,7 +29,7 @@
Documentation is generated by running
+---------------+
- mvn site:site
+mvn site:site
+---------------+
It will generate a plugin site based on the information in the POM, <<<src/site>>> and other reporting
@@ -59,16 +59,17 @@
**Optional Elements
- This might be optional elements in a valid POM but they are important basic project information
+ 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
+ * 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
+ * url - the site of the plugin, normally <maven.apache.org> or <mojo.codehaus.org>
- * prerequisites - would have an initial value of maven, list of descriptive name of dependencies.
+ * prerequisites - the minimum version of Maven required to use this plugin
* issueManagement - describes the system used for reporting problems and modification requests
@@ -81,30 +82,30 @@
[...]
+--------------+
- * inceptionYear - year the plugin was made
+ * inceptionYear - year the plugin was first created
- * mailingLists - list where the developers can be contacted for problems and modification requests
+ * mailingLists - lists where other users or the developers can be contacted for help and discussions
+--------------+
[...]
<mailingLists>
<mailingList>
- <name>Project issues</name>
+ <name>Project users</name>
<post>announce@noonecares.com</post>
- <subscribe>issues-subscribe@noonecares.com</subscribe>
- <unsubscribe>issue-unsubscribe@noonecares.com</unsubscribe>
+ <subscribe>users-subscribe@noonecares.com</subscribe>
+ <unsubscribe>users-unsubscribe@noonecares.com</unsubscribe>
<archive>http://noonecares.archive.org</archive>
</mailingList>
<mailingList>
[...]
- <mailingList>
+ </mailingList>
</mailingLists>
[...]
+--------------+
- * license - plugin license
+ * licenses - plugin license
- * 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
+--------------+
[...]
@@ -116,7 +117,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
+--------------+
[...]
@@ -133,12 +134,12 @@
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.
- * all @parameter field should have a descriptive comment, informative enough that even a regular user can understand.
+ * 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
+ * Put something informative here that a regular user can understand.
*
* @parameter
*/
@@ -146,12 +147,12 @@
[...]
+--------------+
- * class level comment should explain what the goal does.
+ * class level comment should explain what the goal does
+--------------+
[...]
/**
- * Everything here will show up on the top of the generated plugin info page
+ * Everything here will show up on the top of the generated plugin info page.
*
* @goal somegoal
* @phase compile
@@ -165,7 +166,7 @@
[...]
+--------------+
- * all @component and @readonly parameters are not required to have any comments but it's still a good practice to provide one.
+ * the <<<...@component>>> and <<<...@readonly>>> parameters are not required to have any comments but it's still a good practice to provide one
*Site organization
@@ -195,7 +196,7 @@
<item name="description2" href="examples/example-two.html"/>
</menu>
- ${reports}
+ <menu ref="reports"/>
</body>
+--------------+
@@ -249,7 +250,7 @@
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 (Howto)
+ * 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.
@@ -281,7 +282,7 @@
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 :
+ For examples of items under "Examples" check these plugin sites:
{{{http://maven.apache.org/plugins/maven-javadoc-plugin/}Maven Javadoc Plugin Examples}}
@@ -324,11 +325,11 @@
* JXR Report Plugin
- The jxr plugin generates a cross-reference of the project sources. The generated cross-references are also linked to the corresponding
+ The 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 the JXR plugin add the following to your <<<pom.xml>>>
+--------------+
[...]
@@ -346,4 +347,4 @@
[...]
+--------------+
- Check the {{{http://maven.apache.org/plugins/maven-jxr-plugin/jxr-mojo.html}jxr configuration page}} for the possible configuration parameters.
+ Check the {{{http://maven.apache.org/plugins/maven-jxr-plugin/jxr-mojo.html}JXR configuration page}} for the possible configuration parameters.