[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [xtext-dev] API Tooling
|
Sebastian,
here is a note I received from Chris on that topic:
There is no need to "tag" public API... it's simple in Equinox. All
packages that aren't x-internal or x-friends are API.
The model is that you have some control over things that may be API
but aren't meant to be extended, implemented or referenced.
Does that make sense?
More comments below.
On 10.02.2009, at 09:32, Sebastian Zarnekow wrote:
basically I'ld like to declare API as public instead of probiting
usage of all these nice interfaces, classes and methods that we
created, because we can and will not guarantee that they won't
change in the next milestone.
This sounds like a perfect fit for marking them as @noimplement /
@noextend.
The main problem is, that most of our interfaces are likely to
change over time, but this is expected. However clients should be
allowed to use them without any problem (-markers).
I object, as IMO it is essential we tell users exactly which
interfaces we expect to change over time. This will save them all the
hassle of reworking their code when we release a new version of Xtext.
I hoped, that the API tooling would have (javadoc-) annotations like
@experimental,
@stable,
(and @deprecated)
and help us, to fulfil the expectations, that clients would have
when using API that is tagged like this.
It's a pity, that API tooling does it the other way round by marking
interfaces with @noimplement and such.
I am forwarding your suggestions to Chris to see what he thinks about
this. I suppose the Eclipse way of providing experimental stuff would
be to put the classes in packages named
"org.eclipse.xtext.somefeaturename.provisional".
@Chris: do you think it might make sense to add the annotations
Sebastian mentioned above? This would allow people to be a little bit
more expressive about things being provisional / experimental than
just putting things in a package named "provisional".
But I see the advantages of reusing existing solutions.
That's why I suggested using API Tooling in the first place - will
save us time.
Peter
