The following comment has been added to this issue:
Author: M. Sean Gilligan
Created: Wed, 23 Jun 2004 10:51 AM
Body:
The current generate-goals and generate-properties produce xdocs that require
additional hand editing. Also, if you update plugin.jelly or plugin.properties, the
xdocs will not be updated to reflect the change (a message saying the file already
exists and was "skipped" is output.) The current use case is for these goals to
generate a skeleton that is hand edited and then manually maintained after that.
If you look at plugin-resources/templates/properties.jelly, you'll see that the
"Optional?" table entry in properties.xml is always set to "Yes" and the "Description"
field only gets the default value. Any real description must be manually entered.
The plug-in developer is now responsible for keeping plugin.properties and
xdocs/properties.xml in sync.
The "JavaDoc philosophy" is to keep the "code" and the "documentation" in the same
file and to always generate the reference documentation from this single file.
There is more than one way to adopt the JavaDoc philosophy here, so the following are
just possible pieces of a solution:
1) Create a property setting to cause properties.xml and goals.xml to always be
overwritten.
2) Move properties.xml and goals.xml to the "generated-xdocs" folder. (?)
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.
4) Add a <description> child element to the <goal> element in plugin.jelly so a
longer description (with markup?) can be maintained right there.
Obviously, backward-compatibility needs to be addressed, but I don't think that will
be difficult. (Perhaps all this is a suggestion for Maven2.)
---------------------------------------------------------------------
View this comment:
http://jira.codehaus.org/browse/MPPLUGIN-17?page=comments#action_20943
---------------------------------------------------------------------
View the issue:
http://jira.codehaus.org/browse/MPPLUGIN-17
Here is an overview of the issue:
---------------------------------------------------------------------
Key: MPPLUGIN-17
Summary: generate-goals and generate-properties should make more than skeletons
Type: Improvement
Status: Open
Priority: Major
Original Estimate: 1 week
Time Spent: Unknown
Remaining: 1 week
Project: maven-plugin-plugin
Assignee: dion gillard
Reporter: M. Sean Gilligan
Created: Wed, 23 Jun 2004 12:56 AM
Updated: Wed, 23 Jun 2004 10:51 AM
Environment: all
Description:
Rather than generating skeletons of xdoc files, the generate-goals and
generate-properties goals should be extended to parse additional comment information
from plugin.jelly and plugin.properties, so that the "documentation" and the "code"
are in the same file. (In other words, they should work more like JavaDoc.) This will
make documenting plugins and keeping their documentation up-to-date easier and
therefore make the documenation more accurate.
---------------------------------------------------------------------
JIRA INFORMATION:
This message is automatically generated by JIRA.
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
If you want more information on JIRA, or have a bug to report see:
http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
