Hi!
It was great seeing that others have the same problem with complex
objects for Maven configuration and the generated documentation.
For the android maven plugin
http://code.google.com/p/maven-android-plugin/
I have derived a bit of a standard on how we deal with this and we have
implemented that approach for most of the plugin now. There is still
more lingering to do but there is only so much time..
The android maven plugin defines a completely new lifecycle with lots of
custom mojos and invocations and has a LOT of configuration options. We
therefore decided to use the complex object approach.
However that did not work nicely in terms of e.g. a complex object
configuration in the plugin configuration then being overridden in the
command line or with a property.
So here is what we do
- have a plain pojo with no annotations in the configuration package
https://github.com/jayway/maven-android-plugin/tree/master/src/main/java/com/jayway/maven/plugins/android/configuration
- use that as a configuration in the mojo e.g. the RunMojo
https://github.com/jayway/maven-android-plugin/blob/master/src/main/java/com/jayway/maven/plugins/android/standalonemojos/RunMojo.java
with the Run configuration object
- then have another parameter for each one of the attributes of the
configuration object. In the run case it is debug and the used parameter
is runDebug which uses the expression android.run.debug and has a
default value
- then we have a resulting parameter called parsedDebug that is actually
used in the execution
- to derive it we parse the configuration by checking if there is a Run
parameter (e.a. it is defined in the plugin config). if it is we use it
but for each parameter we check if e.g. runDebug is defined and if so we
let it over ride the parameter (therefore command line or property
overrides plugin config).
And then of course we get as much doc into it all as possible.
Now while this is pretty ugly it works well enough and supports plugin
configration, properties (in pom or setting) and command line properties
as well and can produce a reasonable documentation.. sort of.
I have also documented this a bit here
http://code.google.com/p/maven-android-plugin/wiki/CodeConventions
and I maintain the Android chapter in Maven: The Complete Reference and
blog about things when I can to have more documentation..
I would love to hear your thoughts about this approach.
manfred
http://simpligility.com
