We are getting close the chicken and
egg problem here....
When it's time for developers to start
using the tooling, we want to make it easy - so yes, it would be handy
to have a tool that inserts javadoc tags based on existing component XMLs.
I think the tags "replace" component.xml - so I don't think we
should have tooling to keep the two in synch. I would see this as a "one
off" tool to get started. For that reason, I don't think we would
want to create markers as it would require "active" tooling to
keep the two in synch. As well, we'd have to have some mechanism for knowing
if the "component.xml" should be considered as the "source"
for tag generation, or the "target" for caching existing tags.
It feels awkward to have duplicated information in the IDE - when the user
can edit both. Would it be better to have a tool/action/wizard that processes
the component XML and generates a report for issues (rather than makers)?
Does anyone think that we should have
tooling to maintain the "component.xml" files? I'd rather just
use the javadoc tags as the "source" of the information in the
workspace. At build time, we could also use source to generate that part
of our API description.
10/29/2007 02:17 PM
Darin Wright/Ottawa/IBM@IBMCA, Michael
Rennie/Ottawa/IBM@IBMCA, Jeff McAffer/Ottawa/IBM@IBMCA
Using component.xml as a starting point
We should use the existing component.xml
file for each plugin in the SDK to "tag" the corresponding types
with the appropriate javadoc tag.
So the tool would take the component.xml
and check all the API types inside the workspace.
The existing text that describes the
API usage would be replaced with the corresponding tag and for the API
type where the existing text is not an exact match, the tag would be added
and a marker created to remember that this file should be double-checked.
The "new" API types that have
been added since the component.xml was created should also be marked to