Hello,
The generated site documentation for many mojo parameters lacks the nice
info "Default value is <value>" in the parameter summary although the
parameter effectively has a default value. Take for instance the site for
the maven-resources-plugin and its "outputDirectory" parameter [0].
This effect originates from the subtle difference between
/**
* @parameter expression="${project.build.outputDirectory}"
*/
private File outputDirectory;
and
/**
* @parameter default-value="${project.build.outputDirectory}"
*/
private File outputDirectory;
when the PluginXDocGenerator creates the mojo report.
From the user's point of view, there is no difference. In both cases, the
mojo can be used without explicitly specifying a value for the parameter
because a default value will be used. As a matter of consistency, the site
documentation should show this default value, regardless whether it comes
from "expression" or "default-value".
The question is, how can this be realized. I was just about to patch the
PluginXDocGenerator to do some kind of fallback like
if ( StringUtils.isNotEmpty( parameter.getDefaultValue() ) )
{
// report default value
}
else if ( StringUtils.isNotEmpty( parameter.getExpression() ) )
{
// report expression as default value
}
but hesitated when I imagined use-cases like
/**
* @parameter expression="${someSystemProperty}"
*/
private File outputDirectory;
Here the expression is not backed by the POM and hence usually resolves to
null. It would be rather useless to report "${someSystemProperty}" as the
default value.
Currently I believe, plugin developers need to address this individually by
using "default-value" instead of "expression" when appropriate because there
does not seem to be an easy/reliable heuristic how the PluginXDocGenerator
can detect those cases.
A related question is whether it is sensible to do something like
/**
* @parameter expression="${project.build.outputDirectory}"
* @required
*/
private File outputDirectory;
i.e. use a POM-backed expression and also mark the parameter as required.
Again, from the user's point of view, this parameter is not required. It can
be safely ommited in the plugin configuration because the POM expression
will fill it in.
I know, that's all peanuts but Maven's documentation is often critized and I
feel this point is not on the good site. What do you think?
Regards,
Benjamin Bentmann
[0]
http://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
