There are cases where you want a component.xml
file (or something similar) when you don't want to or can't mark up the
source, but I don't see any reason why someone would want to maintain both
a component.xml file and javadoc tags in the source for the same API. So,
a one-off tool for inserting javadoc tags based on a component.xml sounds
useful, but I wouldn't bother getting any fancier than that.
Darin Wright/Ottawa/IBM@IBMCA Sent by: equinox-dev-bounces@xxxxxxxxxxx
10/29/2007 04:54 PM
Please respond to
Equinox development mailing list <equinox-dev@xxxxxxxxxxx>
[equinox-dev] [api tooling] Re: Using
component.xml as a starting point
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
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
So the tool would take the component.xml and check all the API types inside
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 be double-checked.
This could allow us to get a "good" baseline.
What do you think?
equinox-dev mailing list