--- a/graal/com.oracle.graal.graphbuilderconf/src/com/oracle/graal/graphbuilderconf/GraphBuilderContext.java	Wed May 13 13:11:17 2015 +0200
+++ b/graal/com.oracle.graal.graphbuilderconf/src/com/oracle/graal/graphbuilderconf/GraphBuilderContext.java	Wed May 13 13:25:08 2015 +0200
@@ -36,7 +36,8 @@
 import com.oracle.graal.nodes.type.*;
 
 /**
- * Used by a {@link GraphBuilderPlugin} to interface with a graph builder object.
+ * Used by a {@link GraphBuilderPlugin} to interface with an object that parses the bytecode of a
+ * single {@linkplain #getMethod() method} as part of building a {@linkplain #getGraph() graph} .
  */
 public interface GraphBuilderContext {
 
@@ -187,7 +188,7 @@
     }
 
     /**
-     * Gets the method currently being parsed.
+     * Gets the method being parsed by this context.
      */
     ResolvedJavaMethod getMethod();
 
@@ -207,8 +208,8 @@
     JavaType getInvokeReturnType();
 
     /**
-     * Gets the inline depth of this context. 0 implies this is the context for the compilation root
-     * method.
+     * Gets the inline depth of this context. A return value of 0 implies that this is the context
+     * for the parse root.
      */
     default int getDepth() {
         GraphBuilderContext parent = getParent();
@@ -216,7 +217,8 @@
     }
 
     /**
-     * Determines if the current parsing context is a snippet or method substitution.
+     * Determines if this parsing context is within the bytecode of an intrinsic or a method inlined
+     * by an intrinsic.
      */
     default boolean parsingIntrinsic() {
         return getIntrinsic() != null;