I'd really like to contribute to this task, but I'm not aware of the
protocol (for non commiters) to follow since submiting patches to the
plugin post 1.0 is not an options, as I guess, and there's no 1.1 brach,
or is it?
M. Sean Gilligan 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.
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
