| 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, -t From:
eclipse-dev-bounces@xxxxxxxxxxx [mailto:eclipse-dev-bounces@xxxxxxxxxxx] On Behalf Of Ed Burnette
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. |