This may all be moot if we decide to postpone any changes until m2 as suggested by Brett, but I'll update the proposal with Dion's comments (and my responses) just in case people want to go ahead with it:
> > 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. If we use a "generated-xdocs" folder and implement the other changes in #2 below, than I agree that an overwrite property is not necessary. > >> 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 I agree with the addition of (a) and (b). > > > > 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. I don't understand what you mean by "blow out the plugin.jelly script". Mixing code and documentation is generally a good idea when the documentation is minimal and closely tied to the code, two conditions which, I believe, are true in this case. Also, from Brett's post, it seems that mixing the plugin code and documentation is the direction for m2. > > 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 :-) At this point we're mostly in agreement, with the possible exception of #4. Perhaps, though, as Brett suggests, we should just wait for m2 and/or back-port the m2 plugin format for m1. > > > 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. > >Cool. We could add this to the docs for the plugin plugin. Whether we go ahead or not, I'll try to create at least one xdoc for the plugin plugin which addresses how to generate docs. I suppose the go/no-go decision depends on m2. (Please see my separate response on this subject.) -- Sean -- --------------------------------------------------------------------------- M. Sean Gilligan : 831-439-9568 x11 Catalla Systems, Inc. --------------------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
