*IBM Confidential: Re: [eclipse-dev] Best practices for provisional APIs

[Nick Edgar <Nick_Edgar@xxxxxxxxxx>]

Provisional API is closer to internals than to final API.  However, API 
needs to be designed -- it is not just a matter of exposing and blessing 
internals.  So I think it's important to distinguish the provisional API 
(that clients can try out and that may become final API, possibly with 
changes) from the real internal workings.

There are a few cases of provisional API in the Workbench in 3.2.  We've 
tried hard to make this very clear by putting it in internal.provisional 
packages, and putting a big disclaimer in the type's Javadoc comment.  By 
putting it in an internal package, we're clearly stating that the same 
rules apply as for internals: we reserve the right to change the shape of 
it at any time.

See org.eclipse.jface.internal.provisional.actions.ICoolBarManager2 for an 
example.  We're also doing similarly for the data binding framework.

Sometimes this has required some changes to the shape of the provisional 
API.  For example, rather than adding provisional methods to an existing 
abstract class (AbstractPresentationFactory) in an API package, we 
provided the new methods via a mix-in interface 
(IActionBarPresentationFactory) in an internal.provisional package.  This 
requires the workbench to do a bit of extra work (an instanceof check, and 
a default implementation of the interface).  But I feel this approach is 
worth it in order to draw a stronger line between provisional and final 
API.

Nick





Mike Wilson/Ottawa/IBM@IBMCA 
Sent by: eclipse-dev-bounces@xxxxxxxxxxx
02/17/2006 09:01 AM
Please respond to
"General development mailing list of the Eclipse project."


To
"General development mailing list of the Eclipse project." 
<eclipse-dev@xxxxxxxxxxx>
cc

Subject
Re: [eclipse-dev] Best practices for provisional APIs







I find the notion of provisional api to be basically just an oximoron. We 
should have only two categories: API, and things that are internal because 
they haven't yet stabilized/been validated enough to be API. 

McQ. 



Pascal Rapicault/Ottawa/IBM@IBMCA 
Sent by: eclipse-dev-bounces@xxxxxxxxxxx 
02/17/06 08:44 

Please respond to
"General development mailing list of the Eclipse project."


To
eclipse-dev@xxxxxxxxxxx 
cc

Subject
[eclipse-dev] Best practices for provisional APIs









Hi, 

Should we adopt a consistent way to indicate provisional APIs across the 
SDK? 
More specifically I'm wondering what are the rules for 
- the package name. should the API be in the package where it would belong 
if it was real API, or should it be in an internal package? 
- the javadoc markup. should the javadoc say: experimental, provisional, 
something else? 

Aside from those questions, I propose to add to the javadoc an explicit 
request for feedback from the users and explaining where this feedback 
should be given (a mailing-list, a bug report, ...) 

PaScaL_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe 
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev
_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe 
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev