[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [eclipse-pmc] Provisional API guidelines
|
I would add the following information from the current guidelines:
>The primary indicator of provisional API is the @since tag,
indicating that it was introduced during the current development period.
and mention that @provisional (or whatever markup) must be used for those
things that we plan to keep even after the API freeze.
Dani
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|John Arthorne <John_Arthorne@xxxxxxxxxx> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|eclipse-pmc@xxxxxxxxxxx |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|18.03.2010 15:40 |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Re: [eclipse-pmc] Provisional API guidelines |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
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
Jeff McAffer
<jeff@xxxxxxxxxxxxxxxxx>
Sent by: To
eclipse-pmc-bounces@xxxxxxxxxxx eclipse-pmc@xxxxxxxxxxx
cc
03/15/2010 02:20 PM Subject
Re: [eclipse-pmc]
Provisional API
Please respond to guidelines
eclipse-pmc@xxxxxxxxxxx
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
