I think extension points and their related
schemas should be part of the API definition. Component.xml does not cover
them except in the case that you need to access a Java class or implement
a Java interface. I agree that we need to expand our tool coverage to include
extension points. Of course, there is still flexibility in declaring an
extension point as API.
Same goes for any resource that's included
in a plug-in. For example, there may be a set of standard icons that we
want people to use. Clearly we can't just delete those since it would break
clients.
Concerning our implementations of other
APIs, I think we don't have to do anything since our implementations are
already constrained by the semantics of the APIs they implement. We need
to preserve that.
I think there is a simple way to determine
what we need to document as part of our "API". Just ask yourself,
"If I change this can I break clients?" If the answer is "Yes"
then we need to document how clients are allowed to use it, and we need
to add tool support if possible to help us manage it.
To get this process going, I'd like
to ask Jeffrey to extend component.xml to include the declaration of extension
points (and their schemas), and resources that we are proposing as
API. Jeffrey, pls come up with a proposal and post it for review.
David M Williams <david_williams@xxxxxxxxxx> Sent by: wtp-dev-admin@xxxxxxxxxxx
03/17/2005 01:27 PM
Please respond to
wtp-dev
To
wtp-dev@xxxxxxxxxxx
cc
Subject
[wtp-dev] Questions on component.xml
There's probably already been discussion and answers provided for some
questions that immediately came to my mind while starting (and just staring,
mind you :) to define our component.xml files ....
but figured if I didn't know the answer, perhaps it might be worth asking
here so the answers would be repeated for everyone.
One part of our API that gets focus in our component.xml files are classes
or interfaces we implement that we want docs, junits, and java doc. That's
clear enough.
But what about extension points? That's a critical part of a specified
API ... how are they represented in component.xml files?
A more minor case is "ids" ... there's some strings defined via
plugins or extensions that we expect others to use as API (editor IDs,
content menuIDs, are obvious cases). While these can sometimes be redundantly
specified in JavaCode to be used as constants (eg. we've done that for
our contentTypeIds) there's no hard and fast rule that it has to be, or
that it is even always desirable. Its there a suggested way to capture
these IDs which are not defined in Java Code?
Lastly, the hardest, what about our implementations of other's interfaces?
These may be some critical areas to have JUnit test coverage for, but as
far as I can tell, that's a whole other problem not related to component.xml
and our measurements? But in some cases we may need some amount of doc
for? I see this strongly in org.w3c.dom API's ... since we have our own
DOM implementation ... we don't expose our implementation as API per se,
but we do expose it through the org.w3c.dom interface ... that is, obviously,
we expect clients to write code to the org.w3c.dom interface which uses
our implementation (our instance being obtained from one API, naturally).
If this one is carried to extreme, I think we'd find thousands of cases
where we implement base eclipse APIs (either interfaces, or subclassing
such popular classes as 'Plugin', 'ITextEditor', etc). Are any of these
"implementations of others APIs" part of the component.xml files?
[I don't think so, but its a pretty fine line, sometimes, or gives a distorted
picture of "coverage" if not].