Hi Everyone, Thanks for the positive feedback and brainstorming. I made some specific suggestions on JIRA, I'll repeat them here and incorporate/respond-to some suggestions made on the list.
1) Ensure backward-compatibility. One solution is to create a property setting to cause properties.xml and goals.xml to always be overwritten, with a default value of 'false'. We can't have an updated plugin clobber existing hand-written docs. Alternatively if we moved the generated properties.xml and goals.xml to a generated docs folder, we could generate them only if they don't exist in the xdocs (source) folder. That way plugin authors could remove their hand-written docs after updating plugin.jelly and/or plugin.properties to turn on auto-generation. In any event, I think the generation should be a one-way process. Synchronization would be too complicated with little benefit. 2) Move properties.xml and goals.xml to the "generated-xdocs" folder. It is not maven-like to have generated docs in a source directory (unless they are just being generated as "skeletons") this could also be part of the solution to #1. 3) Create a plugin-properties.xml file that can be used to generate both plugin.properties and properties.xml. The xml format can have fields for "Optional", "Default value", "Description', etc. Miguel Griffa may be hinting that the properties definitions/documentation could be added to plugin.jelly. Either way the plugin.properties file would become a generated file. I think using XML is a better solution than inventing another JavaDoc like parser. 4) Add a <description> child element to the <goal> element in plugin.jelly so a longer description (with markup?) can be maintained right there. I'm not sure if HTML markup can be incorporated in plugin.jelly (I don't know what kind of parsers/validation are currently being used.) 5) If all of the above are implemented, an undocumented properties report is probably not necessary, but could be added as an additional mechanism for encouraging better documentation. As I said, I'm willing to contribute but I'll need help from some more experienced Maven folks. Hopefully Dion Gillard will agree this is a useful improvement (again, for the post 1.0 time-frame) and have some time to work on it. I'm not comfortable with Jelly, etc. and I don't understand (well enough) how these kinds of changes will effect the overall Maven system, so I can't create a patch by myself. I'm willing to collect requirements, maintain a design document and help with testing and debugging. I could take the contents of this e-mail, with additional feedback as it comes in, and move it into an xdoc for inclusion in the next plugin-plugin or elsewhere. Since I'm developing my first plugin, I could use the new generation system for it, I could also help convert one or two existing plugins. Regards, Sean > > the properties.xml could be generated with a more advanced >> parsing and >> maybe assuming all properties begin with the plugin name >> followed by a '.' > >The problem will be to standardize the properties documentation and to >parse the file. > ># MY DOC >xxx.xxxx.xxxx=yyyyyyyy > > >> >> Should synchronization be used? >> Why not keep it a one way process? >> >> I think it doesn't make sense to add properties/goals in docs >> which do >> not exist in plugin.jelly, or does it? > >It can be a one-way process. >We must add a report to automatically generate these files before the >site. > >The problem is that in some plugins, the documentation of goals is very >more detailled in the doc than in the plugin.jelly. >In the goal's description you can't use HTML tags. For example : >http://maven.apache.org/reference/plugins/dist/goals.html > > >Arnaud. > > >--------------------------------------------------------------------- >To unsubscribe, e-mail: [EMAIL PROTECTED] >For additional commands, e-mail: [EMAIL PROTECTED] -- --------------------------------------------------------------------------- M. Sean Gilligan : 831-439-9568 x11 Catalla Systems, Inc. --------------------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
