--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/LoopBeginNode.java	Wed Jan 28 15:46:13 2015 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/LoopBeginNode.java	Tue Feb 03 15:29:03 2015 +0100
@@ -78,9 +78,19 @@
     }
 
     /**
-     * Returns the set of {@link LoopEndNode} that correspond to back-edges for this loop, ordered
-     * in increasing {@link #phiPredecessorIndex}. This method is suited to create new loop
-     * {@link PhiNode}.
+     * Returns the set of {@link LoopEndNode} that correspond to back-edges for this loop, in
+     * increasing {@link #phiPredecessorIndex} order. This method is suited to create new loop
+     * {@link PhiNode}.<br>
+     *
+     * For example a new PhiNode may be added as follow:
+     *
+     * <pre>
+     * PhiNode phi = new ValuePhiNode(stamp, loop);
+     * phi.addInput(forwardEdgeValue);
+     * for (LoopEndNode loopEnd : loop.orderedLoopEnds()) {
+     *     phi.addInput(backEdgeValue(loopEnd));
+     * }
+     * </pre>
      *
      * @return the set of {@code LoopEndNode} that correspond to back-edges for this loop
      */
@@ -165,7 +175,7 @@
         return super.verify();
     }
 
-    public int nextEndIndex() {
+    int nextEndIndex() {
         return nextEndIndex++;
     }
 

--- a/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/LoopEndNode.java	Wed Jan 28 15:46:13 2015 +0100
+++ b/graal/com.oracle.graal.nodes/src/com/oracle/graal/nodes/LoopEndNode.java	Tue Feb 03 15:29:03 2015 +0100
@@ -28,6 +28,10 @@
 import com.oracle.graal.nodeinfo.*;
 import com.oracle.graal.nodes.spi.*;
 
+/**
+ * LoopEnd nodes represent a loop back-edge. When a LoopEnd is reached, execution continues at the
+ * {@linkplain #loopBegin() loop header}.
+ */
 @NodeInfo
 public class LoopEndNode extends AbstractEndNode {
 
@@ -79,17 +83,18 @@
     }
 
     /**
-     * Returns the 0-based index of this loop end. This is <b>not</b> the index into {@link PhiNode}
-     * values at the loop begin. Use {@link AbstractMergeNode#phiPredecessorIndex(AbstractEndNode)}
-     * for this purpose.
+     * Returns the index of this loop end amongst its {@link LoopBeginNode}'s loop ends.<br>
      *
-     * @return The 0-based index of this loop end.
+     * Since a LoopBeginNode also has {@linkplain LoopBeginNode#forwardEnds() forward ends}, this is
+     * <b>not</b> the index into {@link PhiNode} values at the loop begin. Use
+     * {@link LoopBeginNode#phiPredecessorIndex(AbstractEndNode)} for this purpose.
+     *
      */
-    public int endIndex() {
+    int endIndex() {
         return endIndex;
     }
 
-    public void setEndIndex(int idx) {
+    void setEndIndex(int idx) {
         this.endIndex = idx;
     }