Skip to main content
Jump to: navigation, search

Difference between revisions of "Xtext/Documentation/API"

m (API lifecycles and contracts in Xtext)
Line 1: Line 1:
 
=== API lifecycles and contracts in Xtext ===
 
=== API lifecycles and contracts in Xtext ===
We distinguish between technical visibility and published API. That means not everything which is technically visible is considered as published or stable API. We have lot's of useful things you may want to use, and we think it's important to allow that but at the same time communicate clearly which bits stay as is and which might be changed in future releases.
+
We distinguish between technically visibile and published API. That means not everything which is technically visible is considered as published or stable API. We have lot's of useful things you may want to use, and we think it's important to allow that but at the same time communicate clearly which bits stay as is and which might be changed in future releases.
  
 
==== @Stable annotation ====
 
==== @Stable annotation ====

Revision as of 12:10, 5 March 2009

API lifecycles and contracts in Xtext

We distinguish between technically visibile and published API. That means not everything which is technically visible is considered as published or stable API. We have lot's of useful things you may want to use, and we think it's important to allow that but at the same time communicate clearly which bits stay as is and which might be changed in future releases.

@Stable annotation

In order to communicate what's stable, we tag interfaces and classes with the annotation @org.eclipse.xtext.Stable.

In most cases we follow a common pattern, where we tag an interface with @Stable and add a pointer to the abstract class you need to subclass in order to be sure that we don't break your code in future releases. This is because we might want to add additional methods to those interfaces. As long as you also subclass a common base class, we can provide default implementations.

Example:

@Stable(since="0.7.0", subClass=AbstractScope.class)
public interface IScope {
   ...
}

@Deprecated annotation

We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. If a stable API is annotated with @Deprecated it means that we might remove it in the next major release. This means that if stable API is annotated with @Deprecated in 0.7.0 it will remain in 0.x but might be removed in 1.x releases.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.