You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Benson Margulies <bi...@gmail.com> on 2012/11/04 20:27:57 UTC
site doc for plugin params of complex type: my favorite bugaboo
Probably the maven 'thing' that frustrates me most frequently is this:
a plugin has a param of class type, and the doc of the param does not
detail the internal structure of the class.
I wonder: could the plugin doc process somehow cooperate with modello, or
something else, to auto-create field-by-field documentation? Can anyone
give me a point to start from in some effort to improve on this?
Re: site doc for plugin params of complex type: my favorite bugaboo
Posted by Hervé BOUTEMY <he...@free.fr>.
Le dimanche 4 novembre 2012 15:27:20 Benson Margulies a écrit :
> Hervé,
>
> What about the following sketch:
>
> Two goals:
>
> 1: to warn when a plugin param is a class type that either (a) cannot be
> mapped by plexus from XML in the POM,
useful, yes: are there known rules to detect such problems?
> or (b) has no documentation for the
> fields.
>
> 2: to include field-by-field documentation.
>
> Neither of these is ideally met by linking to javadoc. If the bean class in
> question starts life as Modello, I would think that we could somehow get a
> copy of the MDO-derived documentation into the plugin site, and link to
> that. If we cannot, currently, then I'd want to start by looking at an
> improvement to MDO to attach annotations to the generated Java code so
> that, later on, we could walk those.
JavaBeans BeanInfo?
>
> Now, given annotations (Really, some simple @Description sort of thing for
> classes and fields), authors of non-MDO classes used in plugin params could
> decorate them.
>
> Do you know how far away my first idea (leaving breadcrumbs in Java classes
> generated by MDO) is from reality?
for the moment, there is nothing like that in Modello, but nothing is
impossible. Java code generator from Modello is JavaModelloGenerator [1]
Regards,
Hervé
[1] http://modello.codehaus.org/modello-plugins/modello-plugin-
java/xref/org/codehaus/modello/plugin/java/JavaModelloGenerator.html
>
> On Sun, Nov 4, 2012 at 2:50 PM, Hervé BOUTEMY <he...@free.fr> wrote:
> > yes, I understand the problem, but didn't find for the moment a way to
> > implement something.
> > I'm interested in working with anybody trying to make something
> >
> > Here are some pointers:
> > - plugin documentation generation is done by PluginXdocGenerator in
> > plugin-
> > tools [1]
> > - Modello model documentation generation is done in XdocGenerator [2]
> >
> > Now, IMHO, we need to choose a plugin goal to look at actual documentation
> > and
> > imagine improvements: do you have some precise goal in mind?
> > assembly:assembly archive parameter [3] for example?
> > When type is not primitive, we could for example try to link to javadoc:
> > not
> > really an XML descriptor, but better than actual "name-only" (and requires
> > already some work to determine from which artifact the class is taken)
> >
> > Perhaps simply start by manually writing something in Mojo's javadoc?
> >
> > WDYT?
> >
> > Regards,
> >
> > Hervé
> >
> >
> > [1] http://maven.apache.org/plugin-tools/maven-plugin-tools-
> >
> > generators/xref/org/apache/maven/tools/plugin/generator/PluginXdocGenerato
> > r.html
> >
> > [2] http://modello.codehaus.org/modello-plugins/modello-plugin-
> > xdoc/xref/org/codehaus/modello/plugin/xdoc/XdocGenerator.html
> >
> > [3]
> > http://maven.apache.org/plugins/maven-assembly-plugin/assembly-mojo.html
> >
> > Le dimanche 4 novembre 2012 14:27:57 Benson Margulies a écrit :
> > > Probably the maven 'thing' that frustrates me most frequently is this:
> > >
> > > a plugin has a param of class type, and the doc of the param does not
> > > detail the internal structure of the class.
> > >
> > > I wonder: could the plugin doc process somehow cooperate with modello,
> > > or
> > > something else, to auto-create field-by-field documentation? Can anyone
> > > give me a point to start from in some effort to improve on this?
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: site doc for plugin params of complex type: my favorite bugaboo
Posted by Benson Margulies <bi...@gmail.com>.
Hervé,
What about the following sketch:
Two goals:
1: to warn when a plugin param is a class type that either (a) cannot be
mapped by plexus from XML in the POM, or (b) has no documentation for the
fields.
2: to include field-by-field documentation.
Neither of these is ideally met by linking to javadoc. If the bean class in
question starts life as Modello, I would think that we could somehow get a
copy of the MDO-derived documentation into the plugin site, and link to
that. If we cannot, currently, then I'd want to start by looking at an
improvement to MDO to attach annotations to the generated Java code so
that, later on, we could walk those.
Now, given annotations (Really, some simple @Description sort of thing for
classes and fields), authors of non-MDO classes used in plugin params could
decorate them.
Do you know how far away my first idea (leaving breadcrumbs in Java classes
generated by MDO) is from reality?
On Sun, Nov 4, 2012 at 2:50 PM, Hervé BOUTEMY <he...@free.fr> wrote:
> yes, I understand the problem, but didn't find for the moment a way to
> implement something.
> I'm interested in working with anybody trying to make something
>
> Here are some pointers:
> - plugin documentation generation is done by PluginXdocGenerator in plugin-
> tools [1]
> - Modello model documentation generation is done in XdocGenerator [2]
>
> Now, IMHO, we need to choose a plugin goal to look at actual documentation
> and
> imagine improvements: do you have some precise goal in mind?
> assembly:assembly archive parameter [3] for example?
> When type is not primitive, we could for example try to link to javadoc:
> not
> really an XML descriptor, but better than actual "name-only" (and requires
> already some work to determine from which artifact the class is taken)
>
> Perhaps simply start by manually writing something in Mojo's javadoc?
>
> WDYT?
>
> Regards,
>
> Hervé
>
>
> [1] http://maven.apache.org/plugin-tools/maven-plugin-tools-
>
> generators/xref/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.html
>
> [2] http://modello.codehaus.org/modello-plugins/modello-plugin-
> xdoc/xref/org/codehaus/modello/plugin/xdoc/XdocGenerator.html
>
> [3]
> http://maven.apache.org/plugins/maven-assembly-plugin/assembly-mojo.html
>
> Le dimanche 4 novembre 2012 14:27:57 Benson Margulies a écrit :
> > Probably the maven 'thing' that frustrates me most frequently is this:
> >
> > a plugin has a param of class type, and the doc of the param does not
> > detail the internal structure of the class.
> >
> > I wonder: could the plugin doc process somehow cooperate with modello, or
> > something else, to auto-create field-by-field documentation? Can anyone
> > give me a point to start from in some effort to improve on this?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
Re: site doc for plugin params of complex type: my favorite bugaboo
Posted by Hervé BOUTEMY <he...@free.fr>.
yes, I understand the problem, but didn't find for the moment a way to
implement something.
I'm interested in working with anybody trying to make something
Here are some pointers:
- plugin documentation generation is done by PluginXdocGenerator in plugin-
tools [1]
- Modello model documentation generation is done in XdocGenerator [2]
Now, IMHO, we need to choose a plugin goal to look at actual documentation and
imagine improvements: do you have some precise goal in mind?
assembly:assembly archive parameter [3] for example?
When type is not primitive, we could for example try to link to javadoc: not
really an XML descriptor, but better than actual "name-only" (and requires
already some work to determine from which artifact the class is taken)
Perhaps simply start by manually writing something in Mojo's javadoc?
WDYT?
Regards,
Hervé
[1] http://maven.apache.org/plugin-tools/maven-plugin-tools-
generators/xref/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.html
[2] http://modello.codehaus.org/modello-plugins/modello-plugin-
xdoc/xref/org/codehaus/modello/plugin/xdoc/XdocGenerator.html
[3] http://maven.apache.org/plugins/maven-assembly-plugin/assembly-mojo.html
Le dimanche 4 novembre 2012 14:27:57 Benson Margulies a écrit :
> Probably the maven 'thing' that frustrates me most frequently is this:
>
> a plugin has a param of class type, and the doc of the param does not
> detail the internal structure of the class.
>
> I wonder: could the plugin doc process somehow cooperate with modello, or
> something else, to auto-create field-by-field documentation? Can anyone
> give me a point to start from in some effort to improve on this?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org