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
|
