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 <[email protected]> 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: [email protected] > For additional commands, e-mail: [email protected] > >
