--- a/graal/com.oracle.truffle.sl/src/com/oracle/truffle/sl/runtime/SLFunction.java	Wed Jan 29 20:43:28 2014 -0800
+++ b/graal/com.oracle.truffle.sl/src/com/oracle/truffle/sl/runtime/SLFunction.java	Wed Jan 29 20:45:43 2014 -0800
@@ -25,10 +25,35 @@
 import com.oracle.truffle.api.*;
 import com.oracle.truffle.api.utilities.*;
 
+/**
+ * Represents a SL function. On the Truffle level, a callable element is represented by a
+ * {@link RootCallTarget call target}. This class encapsulates a call target, and adds versioning
+ * support: functions in SL can be redefined, i.e. changed at run time. When a function is
+ * redefined, the call target managed by this function object is changed (and {@link #callTarget} is
+ * therefore not a final field).
+ * <p>
+ * Function redefinition is expected to be rare, therefore optimzied call nodes want to speculate
+ * that the call target is stable. This is possible with the help of a Truffle {@link Assumption}: a
+ * call node can keep the call target returned by {@link #getCallTarget()} cached until the
+ * assumption returned by {@link #getCallTargetStable()} is valid.
+ * <p>
+ * The {@link #callTarget} can be {@code null}. To ensure that only one {@link SLFunction} instance
+ * per name exists, the {@link SLFunctionRegistry} creates an instance also when performing name
+ * lookup. A function that has been looked up, i.e., used, but not defined, has no call target.
+ */
 public final class SLFunction {
 
+    /** The name of the function. */
     private final String name;
+
+    /** The current implementation of this function. */
     private RootCallTarget callTarget;
+
+    /**
+     * Manages the assumption that the {@link #callTarget} is stable. We use the utility class
+     * {@link CyclicAssumption}, which automatically creates a new {@link Assumption} when the old
+     * one gets invalidated.
+     */
     private final CyclicAssumption callTargetStable;
 
     protected SLFunction(String name) {
@@ -42,6 +67,10 @@
 
     protected void setCallTarget(RootCallTarget callTarget) {
         this.callTarget = callTarget;
+        /*
+         * We have a new call target. Invalidate all code that speculated that the old call target
+         * was stable.
+         */
         callTargetStable.invalidate();
     }
 
@@ -53,8 +82,12 @@
         return callTargetStable.getAssumption();
     }
 
+    /**
+     * This method is, e.g., called when using a function literal in a string concatenation. So
+     * changing it has an effect on SL programs.
+     */
     @Override
     public String toString() {
-        return "function " + name;
+        return name;
     }
 }