--- a/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/inlining/InliningPhase.java	Tue May 13 16:51:41 2014 +0200
+++ b/graal/com.oracle.graal.phases.common/src/com/oracle/graal/phases/common/inlining/InliningPhase.java	Tue May 13 13:20:09 2014 +0200
@@ -93,6 +93,68 @@
         return inliningCount;
     }
 
+    /**
+     * <p>
+     * The space of inlining decisions is explored depth-first with the help of a stack realized by
+     * {@link InliningData}. At any point in time, its topmost element consist of:
+     * <ul>
+     * <li>
+     * one or more {@link GraphInfo}s of inlining candidates, all of them corresponding to a single
+     * callsite (details below). For example, "exact inline" leads to a single candidate.</li>
+     * <li>
+     * the callsite (for the targets above) is tracked as a {@link MethodInvocation}. The difference
+     * between {@link MethodInvocation#totalGraphs()} and {@link MethodInvocation#processedGraphs()}
+     * indicates the topmost {@link GraphInfo}s that might be delved-into to explore inlining
+     * opportunities.</li>
+     * </ul>
+     * </p>
+     *
+     * <p>
+     * The bottom-most element in the stack consists of:
+     * <ul>
+     * <li>
+     * a single {@link GraphInfo} (the root one, for the method on which inlining was called)</li>
+     * <li>
+     * a single {@link MethodInvocation} (the {@link MethodInvocation#isRoot} one, ie the unknown
+     * caller of the root graph)</li>
+     * </ul>
+     *
+     * </p>
+     *
+     * <p>
+     * The stack grows and shrinks as choices are made among the alternatives below:
+     * <ol>
+     * <li>
+     * not worth inlining: pop any remaining graphs not yet delved into, pop the current invocation.
+     * </li>
+     * <li>
+     * process next invoke: delve into one of the callsites hosted in the current candidate graph,
+     * determine whether any inlining should be performed in it</li>
+     * <li>
+     * try to inline: move past the current inlining candidate (remove it from the topmost element).
+     * If that was the last one then try to inline the callsite that is (still) in the topmost
+     * element of {@link InliningData}, and then remove such callsite.</li>
+     * </ol>
+     * </p>
+     *
+     * <p>
+     * Some facts about the alternatives above:
+     * <ul>
+     * <li>
+     * the first step amounts to backtracking, the 2nd one to delving, and the 3rd one also involves
+     * bakctraking (however after may-be inlining).</li>
+     * <li>
+     * the choice of abandon-and-backtrack or delve-into is depends on
+     * {@link InliningPolicy#isWorthInlining} and {@link InliningPolicy#continueInlining}.</li>
+     * <li>
+     * the 3rd choice is picked when both of the previous one aren't picked</li>
+     * <li>
+     * as part of trying-to-inline, {@link InliningPolicy#isWorthInlining} again sees use, but
+     * that's another story.</li>
+     * </ul>
+     * </p>
+     *
+     */
     @Override
     protected void run(final StructuredGraph graph, final HighTierContext context) {
         final InliningData data = new InliningData(graph, context.getAssumptions());