On Wed, 23 Jun 2004 11:02:05 -0700, M. Sean Gilligan <[EMAIL PROTECTED]> wrote: > > 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.
The current process skips generation if the file exists. From my POV, if someone wants to regenerate it, it's easy to just rename the file and re-run the goal. I really don't see the need to introduce an overwrite property. > 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. This would make sense only if: a) The xdocs/ version didn't exist and b) It was a pre-goal of the 'site' goal > > 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. Seems a reasonable thing. > 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.) I don't think this is such a great idea. I'd rather not mix the code and documentation, it'll just blow out the plugin.jelly script. > 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. Yep, once we all agree what's best :-) > 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. Cool. We could add this to the docs for the plugin plugin. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
