[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
*IBM Confidential: Re: [eclipse-dev] Best practices for provisional APIs
|
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