--- a/graal/com.oracle.truffle.api.codegen/src/com/oracle/truffle/api/codegen/NodeChild.java	Mon Jun 03 21:59:44 2013 +0200
+++ b/graal/com.oracle.truffle.api.codegen/src/com/oracle/truffle/api/codegen/NodeChild.java	Tue Jun 18 10:10:54 2013 +0200
@@ -26,6 +26,10 @@
 
 import com.oracle.truffle.api.nodes.*;
 
+/**
+ * A {@link NodeChild} element defines an executable child for the enclosing {@link Node}. A
+ * {@link Node} contains multiple {@link NodeChildren} specified in linear execution order.
+ */
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.TYPE})
 public @interface NodeChild {
@@ -35,13 +39,13 @@
     Class<?> type() default NodeClass.InheritNode.class;
 
     /**
-     * Executes the {@link NodeChild} with values from other defined {@link NodeChild} elements.
-     * These referenced children must be defined before the current node in the execution order. The
-     * current node {@link #type()} attribute must be set to a {@link Node} which supports the
-     * evaluated execution with the number of {@link #executeWith()} arguments that are defined. For
-     * example if this child is executed with one argument, the {@link #type()} attribute must
-     * define a node which publicly declares a method with the signature
-     * <code>Object execute*(VirtualFrame, Object)</code>.
+     * The {@link #executeWith()} property allows a node to pass the result of one child's
+     * executable as an input to another child's executable. These referenced children must be
+     * defined before the current node in the execution order. The current node {@link #type()}
+     * attribute must be set to a {@link Node} which supports the evaluated execution with the
+     * number of {@link #executeWith()} arguments that are defined. For example if this child is
+     * executed with one argument, the {@link #type()} attribute must define a node which publicly
+     * declares a method with the signature <code>Object execute*(VirtualFrame, Object)</code>.
      */
     String[] executeWith() default {};
 }