RE: [eclipse-dev] Best practices for provisional APIs

[Randy Hudson <hudsonr@xxxxxxxxxx>]

Isn't that an argument against using
".internal" (or to enhance the PDE's error flagging)? Do you
the same error flagged when using provisional API vs internal? I think
developers will just end up hiding all restricted access warnings. I hope
it doesn't go the way of the much ignored deprecated warning :-)

-Randy

"Ed Burnette" <Ed.Burnette@xxxxxxx>
Sent by: eclipse-dev-bounces@xxxxxxxxxxx

02/17/2006 10:30 AM

Please respond to
"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>

To	"General development mailing list of the Eclipse project." <eclipse-dev@xxxxxxxxxxx>
cc
Subject	RE: [eclipse-dev] Best practices for provisional APIs

---

From: eclipse-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Randy Hudson

I would prefer just ".provisional" or ".experimental"
prefix in the package name. Clients are more likely to look at the API,
which is the whole point to releasing it in its "unpolished"
state.  Oh .... and it's easier to type. 
 
No, that doesn't work because
Eclipse now has all these access warnings set up that key off of ".internal".
I know that's configurable but...
 
Jeff, would it be good enough
to encourage usage by calling them .internal but having a comment in the
Javadoc that says something to the effect of "Yeah, it's internal
but we expect it to be api soon, so please try it and comment on bug xxx".
And then users can deliberately add those packages to the access whitelist.
To me this is orthogonal to what is done for things you know are going
to be API but are iffy during the milestones, you don't use .internal but
you put a "this is experimental" comment in the javadoc.
 
(If you really wanted to get fancy
you could have a new javadoc tag like '@visibility
x' where 'x' was your confidence level in how stable it was. Maybe something
on whether it was intended to be extended too. The compiler could adjust
diagnostics based on that. But I'm not actually suggesting that.)
_______________________________________________
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