--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/StructuredGraph.java	Fri Sep 13 14:47:04 2013 +0200
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/StructuredGraph.java	Fri Sep 13 15:03:45 2013 +0200
@@ -37,8 +37,33 @@
  */
 public class StructuredGraph extends Graph {
 
+    /**
+     * The different stages of the compilation of a {@link Graph} regarding the status of
+     * {@link GuardNode guards}, {@link DeoptimizingNode deoptimizations} and {@link FrameState
+     * framestates}. The stage of a graph progresses monotonously.
+     * 
+     */
     public static enum GuardsStage {
-        FLOATING_GUARDS, FIXED_DEOPTS, AFTER_FSA
+        /**
+         * During this stage, there can be {@link FloatingNode floating} {@link DeoptimizingNode}
+         * such as {@link GuardNode GuardNodes}. New {@link DeoptimizingNode DeoptimizingNodes} can
+         * be introduced without constraints. {@link FrameState} nodes are associated with
+         * {@link StateSplit} nodes.
+         */
+        FLOATING_GUARDS,
+        /**
+         * During this stage, all {@link DeoptimizingNode DeoptimizingNodes} must be
+         * {@link FixedNode fixed} but new {@link DeoptimizingNode DeoptimizingNodes} can still be
+         * introduced. {@link FrameState} nodes are still associated with {@link StateSplit} nodes.
+         */
+        FIXED_DEOPTS,
+        /**
+         * During this stage, all {@link DeoptimizingNode DeoptimizingNodes} must be
+         * {@link FixedNode fixed}. New {@link DeoptimizingNode DeoptimizingNodes} can not be
+         * introduced any more. {@link FrameState} nodes are now associated with
+         * {@link DeoptimizingNode} nodes.
+         */
+        AFTER_FSA
     }
 
     public static final int INVOCATION_ENTRY_BCI = -1;

--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/FrameStateAssignmentPhase.java	Fri Sep 13 14:47:04 2013 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/FrameStateAssignmentPhase.java	Fri Sep 13 15:03:45 2013 +0200
@@ -33,6 +33,16 @@
 import com.oracle.graal.phases.graph.*;
 import com.oracle.graal.phases.graph.ReentrantNodeIterator.NodeIteratorClosure;
 
+/**
+ * This phase transfers {@link FrameState} nodes from {@link StateSplit} nodes to
+ * {@link DeoptimizingNode DeoptimizingNodes}.
+ * 
+ * This allow to enter the {@link GuardsStage#AFTER_FSA AFTER_FSA} stage of the graph where no new
+ * node that may cause deoptimization can be introduced anymore.
+ * <p>
+ * This Phase processes the graph in post order, assigning the {@link FrameState} from the last
+ * {@link StateSplit} node to {@link DeoptimizingNode DeoptimizingNodes}.
+ */
 public class FrameStateAssignmentPhase extends Phase {
 
     private static class FrameStateAssignmentClosure extends NodeIteratorClosure<FrameState> {

--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/GuardLoweringPhase.java	Fri Sep 13 14:47:04 2013 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/GuardLoweringPhase.java	Fri Sep 13 15:03:45 2013 +0200
@@ -43,9 +43,9 @@
  * This phase lowers {@link GuardNode GuardNodes} into corresponding control-flow structure and
  * {@link DeoptimizeNode DeoptimizeNodes}.
  * 
- * This allow to enter a phase of the compiler where all node that may cause deoptimization are
- * fixed.
- * 
+ * This allow to enter the {@link GuardsStage#FIXED_DEOPTS FIXED_DEOPTS} stage of the graph where
+ * all node that may cause deoptimization are fixed.
+ * <p>
  * It first makes a schedule in order to know where the control flow should be placed. Then, for
  * each block, it applies two passes. The first one tries to replace null-check guards with implicit
  * null checks performed by access to the objects that need to be null checked. The second phase