Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-dev] Best practices for provisional APIs

One objection that’s been raised to “internal.provisional” in the past is that provisional APIs are APIs you hope *not* to change, and that naming convention guarantees you need to change at least that much. FWIW,




From: eclipse-dev-bounces@xxxxxxxxxxx [mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Ed Burnette
Sent: Friday, February 17, 2006 7:31 AM
To: General development mailing list of the Eclipse project.
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.) 

Notice:  This email message, together with any attachments, may contain
information  of  BEA Systems,  Inc.,  its subsidiaries  and  affiliated
entities,  that may be confidential,  proprietary,  copyrighted  and/or
legally privileged, and is intended solely for the use of the individual
or entity named in this message. If you are not the intended recipient,
and have received this message in error, please immediately return this
by email and then delete it.

Back to the top