RE: Improving the documentation of plugins (was maven is hard)

[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