--- a/graal/com.oracle.truffle.sl/src/com/oracle/truffle/sl/nodes/SLTypes.java	Wed Jan 29 20:43:28 2014 -0800
+++ b/graal/com.oracle.truffle.sl/src/com/oracle/truffle/sl/nodes/SLTypes.java	Wed Jan 29 20:45:43 2014 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,22 +25,47 @@
 import java.math.*;
 
 import com.oracle.truffle.api.dsl.*;
+import com.oracle.truffle.sl.*;
 import com.oracle.truffle.sl.runtime.*;
 
-@TypeSystem({long.class, BigInteger.class, boolean.class, String.class, SLFunction.class, SLNull.class, Object[].class})
-public class SLTypes {
+/**
+ * The type system of SL, as explained in {@link SLMain}. Based on the annotation {@link TypeSystem}
+ * , the Truffle DSL generates the subclass {@link SLTypesGen} with type test and type conversion
+ * methods for all types. In this class, we only cover types where the automatically generated ones
+ * would not be sufficient.
+ */
+@TypeSystem({long.class, BigInteger.class, boolean.class, String.class, SLFunction.class, SLNull.class})
+public abstract class SLTypes {
 
+    /**
+     * Example of a manually specified type check that replaces the automatically generated type
+     * check that the Truffle DSL would generate. For {@link SLNull}, we do not need an
+     * {@code instanceof} check, because we know that there is only a {@link SLNull#SINGLETON
+     * singleton} instance.
+     */
     @TypeCheck
     public boolean isSLNull(Object value) {
-        return SLNull.INSTANCE == value;
+        return value == SLNull.SINGLETON;
     }
 
+    /**
+     * Example of a manually specified type cast that replaces the automatically generated type cast
+     * that the Truffle DSL would generate. For {@link SLNull}, we do not need an actual cast,
+     * because we know that there is only a {@link SLNull#SINGLETON singleton} instance.
+     */
     @TypeCast
     public SLNull asSLNull(Object value) {
         assert isSLNull(value);
-        return SLNull.INSTANCE;
+        return SLNull.SINGLETON;
     }
 
+    /**
+     * Informs the Truffle DSL that a primitive {@code long} value can used in all specializations
+     * where a {@link BigInteger} is expected. This models the semantic of SL: It only has an
+     * arbitrary precision Number type (implemented as {@link BigInteger}, and {@code long} is only
+     * used as a performance optimization to avoid the costly {@link BigInteger} arithmetic for
+     * values that fit into a 64-bit primitive value.
+     */
     @ImplicitCast
     public BigInteger castBigInteger(long value) {
         return BigInteger.valueOf(value);