[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [xtext-dev] API Tooling
|
Peter,
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.
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 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.
But I see the advantages of reusing existing solutions.
- Sebastian
Am 10.02.2009 um 14:49 schrieb Peter Friese:
Sebastian,
as you basically vetoed using the API Tooling, I'd be interested in
hearing your take on this? Do you have a suggestion for tagging
public API?
Peter
On 10.02.2009, at 04:48, Sebastian Zarnekow wrote:
-1
I'm afraid that these tags are to restrictive. As far as I'm
concerned, I wouldn't use any marker, that results in any "client
must not" constraint.
Regards
- Sebastian
Am 10.02.2009 um 10:13 schrieb Jan Köhnlein:
+1 from my side
Am 10.02.2009 um 08:53 schrieb Sven Efftinge:
So, than no extra dependencies. That's nice.
+1 for using these tags.
On Feb 10, 2009, at 8:47 AM, Bernd Kolb wrote:
AFAIK these are not annotations but Javadoc comments
Bernd
Zitat von Sven Efftinge <sven@xxxxxxxxxxx>:
That would mean to introduce a dependency to the annotations.
What's the bundle's name the annotations are included in?
Cheers,
Sven
On Feb 9, 2009, at 9:38 PM, Peter Friese wrote:
Guys,
I just had a look at the API tooling. To me, the API tooling
looks very powerful, but we do not need to use everything of
it.
So here's what we would need to do to use it:
1) Add an API Tooling Nature and the API tooling Builder to
each Xtext project. This is actually quite easy, there is a
UI action to do this (project context menu -> PDE Tools ->
API Tooling Setup, then select all Xtext projects).
2) Next, add JavaDoc Annotations to all public, yet not-to-be-
extended classes, interfaces and methods. We only need to
annotate classes and interfaces that are located in exported
packages, as non-exported classes and interfaces will not be
visible to downstream bundles anyway.
Here is a list of the relevant tags:
@noimplement (Interfaces) - Indicates that clients must not
implement this interface. Any class using the implements or
extends keyword for the associated interface will be flagged
with problem.
@noextend (Classes) - Indicates that clients must not extend
this class. Any class using the extends keyword for the
associated class will be flagged with a problem.
@noinstantiate (Classes) - Indicates that clients must not
instantiate this class. Any code that instantiates the
associated class with any constructor will be flagged with a
problem.
@nooverride (Methods) - Indicates that clients must not
redeclare this method. Any subclass that defines a method
that overrides the associated method will be flagged with a
problem.
@noreference (Methods, constructors and fields (nonfinal)) -
Indicates that clients must not reference this method,
constructor, or nonfinal field. Any code that directly
invokes the associated method or constructor or references
the associated nonfinal field will be flagged with a problem.
That's it.
Additionally, we can later
3) Define a shipped version of Xtext to be a so-called API
Baseline. Eclipse will then scan the bundles in this version
and make sure we do not break API by removing or renaming
public classes, interfaces and methods.
Here is a nice developerWorks article that gives a good
overview of what can be achieved with the API tooling: http://www.ibm.com/developerworks/opensource/library/os-eclipse-api-tools/index.html
. Even more information can be found here: http://wiki.eclipse.org/PDE/API_Tools
In the above mentioned developerWorks article it is mentioned
that API tooling can be used headless, which is very nice as
well.
As API tooling seems to be quite mature and since we will not
get any additional dependencies to PDE (besides the
additional nature and builder), I suggest using API tooling.
Cheers,
Peter
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
Mit freundlichen Grüßen
B.Kolb
_______________________
KolbW@re
Beratung und Coaching
Franz-Marc Str. 35
89520 Heideinheim
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
--
Dr. Jan Köhnlein
Senior Software Architekt
Telefon: +49 (0) 431 / 5606-337
Mobile: +49 (0) 151 / 17396687
Telefax: +49 (0) 431 / 5606-339
http://www.itemis.de
jan.koehnlein@xxxxxxxxx
itemis AG
Niederlassung Kiel
Schauenburgerstr. 116
24118 Kiel
http://www.itemis.de/
Rechtlicher Hinweis:
Registergericht: Amtsgericht Dortmund HRB 20621
Sitz der Gesellschaft: Lünen
Vorstand: Wolfgang Neuhaus, Jens Wagener, Dr. Georg Pietrek
Aufsichtsrat: Prof. Dr. Burkhard Igel (Vorsitzender), Stephan
Grollmann, Michael Neuhaus
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
_______________________________________________
xtext-dev mailing list
xtext-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/xtext-dev
