| I was not trying to win anyone over particularly but cool. I'm glad to have *some* markup somewhere. The manifest is my natural bias for the reasons outlined. JavaDoc is also useful.
I agree that this is not a rush but... The real target we want to hit is getting the markup in. The tooling etc can come later. At least in the guidelines it is confusing to say that provisional stuff is "x-internal" but then say that we want to have new markup to mark provisional stuff.
Bug 234947 outlines one form of manifest markup. So if we can settle on something there, it is an easy recommendation. As we have seen, it is extremely hard to change the community and mixed/changing messages just leads to confusion and frustration. I suggest that if we publish these guidelines, we solidify as much as possible.
For JavaDoc markup I am less certain. We can just say "put @provisional as necessary". Not sure if more than that is needed. The freeform text can then be replaced IMHO.
Jeff
On 2010-03-18, at 10:39 AM, John Arthorne wrote:
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.
John
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.
Jeff
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 [1]. 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 [2].
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
that.
John
[1] http://wiki.eclipse.org/Provisional_API_Guidelines_Update_Proposal
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=234947_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
|
