RE: [eclipse-pmc] Provisional API guidelines
IMO having something machine-processable is always good,
even if we don't process it today. Otherwise we end up searching for string
matches, missing typos or strings with different line wrapping, ... when we do
want a tag in the future.
On one of the related bugs, a year or so ago I
explored how a new tag can be added to the Javadoc compiler.
I do like the idea of there being
some indication in the javadoc that the API is provisional. Do you think it is
valuable to define a javadoc tag for this, or just have a paragraph explaining
it? In the past we have just added a blurb like this into the class
class/interface is part of an interim API that is still under development and
expected to * change
significantly before reaching stability. It is being made available at this
early stage to solicit feedback * from pioneering adopters on the understanding that any code that
uses this API will almost certainly be broken * (repeatedly) as the API evolves.
+1, two more points:
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx
03/18/2010 10:51 AM
|RE: [eclipse-pmc] Provisional API
- While manifest markup should be
mandatory, Javadoc markup ("@provisional") should also be encouraged in
addition to that. Think about generated Javadocs read on a web server, where
the manifest is not available (and yes I do know that whether provisional API
should be generated as Javadocs or not is a separate question).
- Provisional API can be distinguished
from internal code today, when the internal code has a **/internal/** path
segment. Perhaps this could be leveraged by tooling if related filters are
[mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of John
Sent: Thursday, March 18, 2010 3:40 PM
Subject: Re: [eclipse-pmc] Provisional API
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.
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.
to talk about how to indicate provisional-ness on packages. In the
- 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 that.