2.1 and 2.2 are often non-useful.
Examples that don't show the <groupId> tag can be confusing. Maybe that's
just me but the <artifactId> in the example isn't enough. I think it has
something to do with plugins moving around from codehaus to maven to apache
and such.
Sometimes there are example of complicated things and no example of the
simple thing. I find the examples the best help for me.
I don't usually find the part that looks like this useful:
*jarName* The name of the jar file.
- *Type*: java.lang.String
- *Required*: Yes
- *Expression*: ${project.build.finalName}
5.1 and 5.2 are frustrating because they often have just enough info to make
you think you know enough to use them.
For example, there are often "path" options but you don't know where they
path begins. Does it begin in the folder containing the POM that contains
the option itself? Or does it begin in the folder containing the POM that we
are currently building? (Parent or child pom location) Or does it begin in
the folder you were in when you typed "mvn"? What does ".." do when its at
the front of the path? Does the path specified in a parent pom get the path
from the parent to the child pom added to what was specified? The docs
should tell, in each case, exactly how that works.
On 9/28/07, Dennis Lundberg <[EMAIL PROTECTED]> wrote:
>
> 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.xmlfile.
>
> 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]
>
>
--
-- Lee Meador
Sent from gmail. My real email address is lee AT leemeador.com
