In this thread I would like to focus on one aspect of the "maven is
hard" thread, namely documentation for plugin options.
Here's a quick run down on the different parts that a plugin site
consists of and how they are generated.
1. Navigation
The menu on the left hand side is specified in the /src/site/site.xml
file for each plugin. It's contents (which sub menus to have and the
names of menu options) is standardized in [1] and can be checked with
the use of [2].
2. Overview (sub menu)
2.1 Introduction
This is a created from a template as specified in [1].
The source for this page is found in /src/site/apt/index.apt
2.2 Usage
This page is not very regulated. It should contain "easy" examples, to
give beginners an overview of how the plugin is used.
The source for this page is found in /src/site/apt/usage.apt
2.3 FAQ
The source for this page is found in /src/site/fml/faq.apt
3. Examples (sub menu)
This is the place for advanced examples.
The source for these pages should be found in the
/src/site/apt/examples/ folder
4. Project Documentation (sub menu)
4.1 Project Information
This is all auto-generated pages with the info taken from the pom.xml file.
4.2 Project Reports
These pages are generated by reporting plugins.
5. Goals pages
5.1 Plugin documentation (all goals)
An auto-generated page which lists all the available goals (or mojos)
for a plugin. The description part is taken from the JavaDoc for the
class for that particular goal.
5.2 Options (one goal)
An auto-generated page which lists all the available options for a goal.
The description part is taken from the JavaDoc for the variable in the
java source file for that goal.
Now on to the first question for all users out there:
Which of the numbered items above needs more work?
Please be either concrete with examples like:
"option A for goal B in plugin C is really bad"
or give more general thoughts that are valid for all plugins [3] at the
Maven project.
Please try to keep this thread on topic.
References:
[1] The Plugin Documentation Standard
http://maven.apache.org/guides/development/guide-plugin-documentation.html
[2] Maven Documentation Checker Plugin:
http://maven.apache.org/plugins/maven-docck-plugin/
[3] Plugins at the Maven project
http://maven.apache.org/plugins/index.html
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
