[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] Questions on component.xml


David,

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.

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@xxxxxxx
intranet: http://labweb.torolab.ibm.com/DRY6/



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].


Thanks for any advice.