--- a/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/TypeCast.java	Mon Jan 05 20:23:22 2015 +0100
+++ b/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/TypeCast.java	Mon Jan 05 20:23:22 2015 +0100
@@ -26,8 +26,30 @@
 
 import java.lang.annotation.*;
 
+/**
+ * Overrides the standard way of casting a certain type in a {@link TypeSystem}. This is useful for
+ * types where the guest language specific type cast can be implemented more efficiently than an
+ * instanceof check. The annotated method must be contained in a {@link TypeSystem} annotated class.
+ * Type checks must conform to the following signature: <code>public static Type as{TypeName}(Object
+ * value)</code>. The casted type must be a type declared in the {@link TypeSystem}.
+ *
+ * <p>
+ * If no {@link TypeCast} is declared then the type system implicitly uses a type cast that can be
+ * declared as follows:
+ *
+ * <pre>
+ * {@literal @}TypeCast(Type.class)
+ * public static Type asType(Object value) {
+ *         return (Type) value;
+ * }
+ * </pre>
+ *
+ * @see TypeCheck
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.METHOD})
 public @interface TypeCast {
 
+    Class<?> value();
+
 }