You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Dennis Lundberg <de...@apache.org> on 2007/09/28 23:55:12 UTC
Improving the documentation of plugins (was maven is hard)
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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Improving the documentation of plugins (was maven is hard)
Posted by Jeff Jensen <je...@upstairstechnology.com>.
> -----Original Message-----
> From: Dennis Lundberg [mailto:dennisl@apache.org]
> Sent: Friday, September 28, 2007 5:41 PM
> To: Maven Users List
> Subject: Re: Improving the documentation of plugins (was maven is hard)
[snip]
> > 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.
With this type of example, it is the most difficult when there is no
sample/example. So, no matter how it is accomplished (a link to common
defs, inline, etc.), every option needs defined: description, default value,
and at least a couple of example usages. The examples, when I have seen
them, have really expressed what the vague description was.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Improving the documentation of plugins (was maven is hard)
Posted by Dennis Lundberg <de...@apache.org>.
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 <de...@apache.org> 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: users-unsubscribe@maven.apache.org
>> For additional commands, e-mail: users-help@maven.apache.org
>>
>>
>
>
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Improving the documentation of plugins (was maven is hard)
Posted by Lee Meador <le...@leemeador.com>.
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 <de...@apache.org> 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: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
-- Lee Meador
Sent from gmail. My real email address is lee AT leemeador.com
Re: Improving the documentation of plugins (was maven is hard)
Posted by Tristan Cebulla <eq...@lichtspiele.org>.
Tristan Cebulla wrote:
>
> Stupid trying out can be very tedious and I don't want to sit eight hours
> every day long testing options/parameters to get it work properly ;)
>
>
> Regards,
> Tristan Cebulla
>
Just to correct my last post: it was not intended to sound rigorous, I'm
just looking for some way to get the plugin work by instancing it from a
(master) pom.xml for all projects linked to that master POM.
I did not find something about that in the usage documentation so it would
be nice if there would be some :)
Regards,
Tristan Cebulla
--
View this message in context: http://www.nabble.com/Improving-the-documentation-of-plugins-%28was-maven-is-hard%29-tf4537045s177.html#a12980823
Sent from the Maven - Users mailing list archive at Nabble.com.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Improving the documentation of plugins (was maven is hard)
Posted by Raphaël Piéroni <ra...@gmail.com>.
Hi,
the dashboard plugin is still snapshot and reside in the mojo sandbox.
It not yet being released.
Raphaël
2007/10/1, Brian E. Fox <br...@reply.infinity.nu>:
>
> The mojo project has mailing lists
> (http://mojo.codehaus.org/mail-lists.html) for those projects.
>
> -----Original Message-----
> From: Tristan Cebulla [mailto:equinox@lichtspiele.org]
> Sent: Monday, October 01, 2007 9:55 AM
> To: users@maven.apache.org
> Subject: Re: Improving the documentation of plugins (was maven is hard)
>
>
>
> Dennis Lundberg-2 wrote:
> >
> > 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.
> >
>
> Hi there,
>
> I'm using the dashboard-maven-plugin
> (http://mojo.codehaus.org/dashboard-maven-plugin/) , but I didn't find
> any
> useful/complete documentation about the plugin configuration parameters,
> especially for XML usage in a pom.xml/master POM.
>
> Stupid trying out can be very tedious and I don't want to sit eight
> hours
> every day long testing options/parameters to get it work properly ;)
>
>
> Regards,
> Tristan Cebulla
> --
> View this message in context:
> http://www.nabble.com/Improving-the-documentation-of-plugins-%28was-mave
> n-is-hard%29-tf4537045s177.html#a12979567
> Sent from the Maven - Users mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
RE: Improving the documentation of plugins (was maven is hard)
Posted by "Brian E. Fox" <br...@reply.infinity.nu>.
The mojo project has mailing lists
(http://mojo.codehaus.org/mail-lists.html) for those projects.
-----Original Message-----
From: Tristan Cebulla [mailto:equinox@lichtspiele.org]
Sent: Monday, October 01, 2007 9:55 AM
To: users@maven.apache.org
Subject: Re: Improving the documentation of plugins (was maven is hard)
Dennis Lundberg-2 wrote:
>
> 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.
>
Hi there,
I'm using the dashboard-maven-plugin
(http://mojo.codehaus.org/dashboard-maven-plugin/) , but I didn't find
any
useful/complete documentation about the plugin configuration parameters,
especially for XML usage in a pom.xml/master POM.
Stupid trying out can be very tedious and I don't want to sit eight
hours
every day long testing options/parameters to get it work properly ;)
Regards,
Tristan Cebulla
--
View this message in context:
http://www.nabble.com/Improving-the-documentation-of-plugins-%28was-mave
n-is-hard%29-tf4537045s177.html#a12979567
Sent from the Maven - Users mailing list archive at Nabble.com.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Improving the documentation of plugins (was maven is hard)
Posted by Dennis Lundberg <de...@apache.org>.
Tristan Cebulla wrote:
>
> Dennis Lundberg-2 wrote:
>> 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.
>>
>
> Hi there,
>
> I'm using the dashboard-maven-plugin
> (http://mojo.codehaus.org/dashboard-maven-plugin/) , but I didn't find any
> useful/complete documentation about the plugin configuration parameters,
> especially for XML usage in a pom.xml/master POM.
>
> Stupid trying out can be very tedious and I don't want to sit eight hours
> every day long testing options/parameters to get it work properly ;)
>
>
> Regards,
> Tristan Cebulla
Hi,
I had a quick glance and it seems that this plugin, which belongs to the
Mojo project over at the Codehaus, has not been released yet. It is
still in their sandbox. I guess you can expect the docs to be in the
same state as the plugin - not yet finished.
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Improving the documentation of plugins (was maven is hard)
Posted by Tristan Cebulla <eq...@lichtspiele.org>.
Dennis Lundberg-2 wrote:
>
> 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.
>
Hi there,
I'm using the dashboard-maven-plugin
(http://mojo.codehaus.org/dashboard-maven-plugin/) , but I didn't find any
useful/complete documentation about the plugin configuration parameters,
especially for XML usage in a pom.xml/master POM.
Stupid trying out can be very tedious and I don't want to sit eight hours
every day long testing options/parameters to get it work properly ;)
Regards,
Tristan Cebulla
--
View this message in context: http://www.nabble.com/Improving-the-documentation-of-plugins-%28was-maven-is-hard%29-tf4537045s177.html#a12979567
Sent from the Maven - Users mailing list archive at Nabble.com.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org