Lee Meador wrote:
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.
Yes I totally agree, all examples *must* show both groupId and
artifactId. I'll add some text about how to write good pom examples in
the documentation standard.
Sometimes there are example of complicated things and no example of the
simple thing. I find the examples the best help for me.
This is where we need your help. To fill in the missing pieces. Please
open a JIRA for that plugin when you are missing an example. It can be
that you need either a simpler example or a more advanced one.
Suppose you get help, and an example, from someone on the user list and
you think it should be added to the plugin site. If you can't create a
patch yourself, then add a link in the JIRA issue to the relevant
mail-thread in one of the mail archives:
http://maven.apache.org/mail-lists.html
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}
I don't know which plugin the is for. How can we improve that particular
option?
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.
Good point. Perhaps we could have a general page about how different
types of options (like File) should be specified, and in your example
where their root is. The we create an automatic link to that page for
each such option.
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]
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
