--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java	Thu Dec 10 18:51:41 2015 +0100
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java	Thu Dec 10 18:18:32 2015 +0100
@@ -90,7 +90,7 @@
     /**
      * Adds frame slot. Delegates to
      * {@link #addFrameSlot(java.lang.Object, java.lang.Object, com.oracle.truffle.api.frame.FrameSlotKind)
-     * addFrameSlot}(identifier, <code>null</code>, {@link FrameSlotKind#Illegal}). This is slow
+     * addFrameSlot}(identifier, <code>null</code>, {@link FrameSlotKind#Illegal}). This is a slow
      * operation that switches to interpreter mode.
      *
      * @param identifier key for the slot
@@ -103,8 +103,8 @@
     /**
      * Adds frame slot. Delegates to
      * {@link #addFrameSlot(java.lang.Object, java.lang.Object, com.oracle.truffle.api.frame.FrameSlotKind)
-     * addFrameSlot}(identifier, <code>null</code>, <code>kind</code>). This is slow operation that
-     * switches to interpreter mode.
+     * addFrameSlot}(identifier, <code>null</code>, <code>kind</code>). This is a slow operation
+     * that switches to interpreter mode.
      *
      * @param identifier key for the slot
      * @param kind the kind of the new slot
@@ -115,7 +115,7 @@
     }
 
     /**
-     * Adds new frame slot to {@link #getSlots()} list. This is slow operation that switches to
+     * Adds new frame slot to {@link #getSlots()} list. This is a slow operation that switches to
      * interpreter mode.
      *
      * @param identifier key for the slot - it needs proper {@link #equals(java.lang.Object)} and
@@ -136,7 +136,7 @@
     }
 
     /**
-     * Finds an existing slot. This is slow operation.
+     * Finds an existing slot. This is a slow operation.
      *
      * @param identifier the key of the slot to search for
      * @return the slot or <code>null</code>
@@ -147,7 +147,7 @@
     }
 
     /**
-     * Finds an existing slot or creates new one. This is slow operation.
+     * Finds an existing slot or creates new one. This is a slow operation.
      *
      * @param identifier the key of the slot to search for
      * @return the slot
@@ -161,7 +161,7 @@
     }
 
     /**
-     * Finds an existing slot or creates new one. This is slow operation.
+     * Finds an existing slot or creates new one. This is a slow operation.
      *
      * @param identifier the key of the slot to search for
      * @param kind the kind for the newly created slot
@@ -176,7 +176,7 @@
     }
 
     /**
-     * Finds an existing slot or creates new one. This is slow operation.
+     * Finds an existing slot or creates new one. This is a slow operation.
      *
      * @param identifier the key of the slot to search for
      * @param info info for the newly created slot
@@ -193,7 +193,7 @@
 
     /**
      * Removes a slot. If the identifier is found, its slot is removed from this descriptor. This is
-     * slow operation.
+     * a slow operation.
      *
      * @param identifier identifies the slot to remove
      */
@@ -263,11 +263,21 @@
         return clonedFrameDescriptor;
     }
 
+    /**
+     * Invalidates the current, and create a new version assumption.
+     */
     void updateVersion() {
         version.invalidate();
         version = createVersion();
     }
 
+    /**
+     * Returns an assumption reflecting the frame's current version, which is updated every time a
+     * slot is added or removed, or an existing slot's kind is changed. This assumption is
+     * associated with compiled code that depends on the internal frame layout.
+     *
+     * @return an assumption invalidated when a slot is added or removed, or a slot kind changed.
+     */
     public Assumption getVersion() {
         return version;
     }
@@ -285,6 +295,14 @@
         return defaultValue;
     }
 
+    /**
+     * Make an assumption that no slot with the specified identifier is present in this frame
+     * descriptor. Invalidated when a frame slot with the identifier is added.
+     *
+     * @param identifier frame slot identifier
+     * @return an assumption that this frame descriptor does not contain a slot with the identifier
+     * @throws IllegalArgumentException if the frame descriptor contains a slot with the identifier
+     */
     public Assumption getNotInFrameAssumption(Object identifier) {
         if (identifierToSlotMap.containsKey(identifier)) {
             throw new IllegalArgumentException("Cannot get not-in-frame assumption for existing frame slot!");