RE: [eclipse-pmc] Provisional API guidelines
Well I would expect the @provisional on each class, since
otherwise it's too easy to miss when reading Javadocs.
At such future time as we explore something like
@provisional, it might be good (for consistency's sake) to support these as Java
annotations on the package, rather than just javadoc.
I'm no fan of package-level annotations in general but
this seems like an appropriate use.
These points have won me over to
the side of manifest markup, in particular the need for pure binary bundles to
indicate their API-ness regardless of availability of javadoc. However at this
point in the release cycle I'm not sure the framework and tooling teams have
the time to implement new manifest markup and tooling in time for Helios.
In the end this seems like a nice
thing to have, but seems separate from whether we adopt your proposed new
provisional API guidelines. With both old and new guidelines, provisional API
is marked x-internal. A different manifest attribute would make it a little
easier for clients to distinguish their use of internals from use of
provisional, presumably with the benefit that they can ignore warnings about
using provisional API without ignoring warnings about other internals. This
doesn't seem like an urgent enough benefit for us to push on getting this
supported added for Helios.
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx
03/15/2010 02:20 PM
|Re: [eclipse-pmc] Provisional API
The reason I liked the manifest markup is for "consistency" with the
x-internal/x-friends tags which really talk about what is API and who can use
it (e.g., the contract). Having said that, there is an element of history
here. Traditionally the manifest markup was what was driving the tools. With
the advent of API tools etc, this kind of JavaDoc markup is more interesting.
Some random thoughts:
- You must be able to ship a
binary bundle and indicate what parts are provisional such that I get errors
when I develop code using those provisional API (assuming I say I don't want
to use provisioning bits) then we have the bulk of the function we need.
- Have to talk about how to indicate
provisional-ness on packages. In the package.html? Where?
- Reconcile the multiple locations for markup related to
package API-ness (some in manifest, some somewhere else, ...)
Summary: I would like there to be some markup.
On 2010-03-15, at
2:03 PM, John Arthorne wrote:
At last week's PMC call, we discussed formally adopting Jeff's
proposed update to our provisional API guidelines . Overall we were in
agreement on the direction, but the question was raised whether additional
markup and tooling were needed to distinguish provisional API from other
internal packages. One approach to doing this would be additional manifest
markup as described in bug 234947 .
I have been thinking that another approach would be
a javadoc tag such as @provisional in the code itself. One advantage of this
is that it puts markup directly in the code where clients are more likely to
see it even if their tools are configured to ignore the warnings. It would
also allow for finer-than-package granularity of provisional API, although I'm
not convinced we need or want that. Conversely, manifest markup allows
multiple providers of the same package to declare different intent (one could
export a package provisionally, while another might declare as full API). I'm
not sure if that use case makes any sense, I'm just trying to think through
what advantages manifest markup has over markup in the code itself. I must be
missing some reasons here but hopefully Jeff and Tom can chime in on