Comments on: Xtext M6 with more documentation and stable API

By: 11:60 p.m. » Blog Archive » New Xtext Logo

11:60 p.m. » Blog Archive » New Xtext Logo — Sun, 07 Jun 2009 21:49:28 +0000

[...] case. Eventually, we realized that the omnipresent logo started with a lower-case “x” (convince yourself). So it was out own [...]

By: Heiko Behrens

Heiko Behrens — Thu, 19 Mar 2009 14:08:39 +0000

@Jens: And yes, OmniGraffle rocks!

By: Heiko Behrens

Heiko Behrens — Thu, 19 Mar 2009 14:07:53 +0000

@Jens Yes, the @stable annotation is Xtext specific. We decided to place it there and limit the possibilities of reuse. On the other hand, its implementation is not that complex

@Target({ ElementType.TYPE})
public @ interface Stable {
String since();
Class< ?> subClass() default Object.class;
}

and an Xtext specific annotation allows you to find every stable aspect of the API by a simple “Find References”.

By: Heiko Behrens

Heiko Behrens — Thu, 19 Mar 2009 13:55:01 +0000

@Gunnar: We had this discussion, too. See http://dev.eclipse.org/mhonarc/lists/xtext-dev/msg00187.html as a starting point of this thread in the mailing list. Eventually, we settled with the annotation partly due to tooling capabilites (e.g. “Find References”). Also, the Eclipse API tooling has a resticting tone whereas the @stable annotation declares stable parts. Last not least we want to generate code against interfaces that are not marked as stable. Since Eclipse API tooling cannot distinguish between generated and manually written code this might cause false errors.

By: Jens v.P.

Jens v.P. — Thu, 19 Mar 2009 13:13:28 +0000

As fas as I understand these annotations, they are not Xtext related, are they? Would be nice to have something like that available for other projects, too.

BTW: I figure the diagram was created with OmniGraffle, wasn’t it? Frankly, I create my diagrams with OmniGraffle, too. Isn’t that weird? Working with GEF everyday, I still use OmniGraffle if I want to produce nice diagrams… Hmm… we definitely have to improve these Eclipse graphical editor things.

By: Gunnar

Gunnar — Thu, 19 Mar 2009 10:54:17 +0000

Heiko, why didn’t you use API tooling but introduced yet another markup that people need to learn?

I understand that annotations look stronger than JavaDoc tags. But Eclipse API tags are great for expressing what your @Stable annotation does. Plus, they integrate nicely with the Eclipse API tooling.

Example:
@noimplement This interface is not intended to be implemented by clients directly. They must subclass {@link SomeBaseClass} instead.