# HG changeset patch
# User Josef Eisl <josef.eisl@jku.at>
# Date 1405358855 -7200
# Node ID b07f96c783ad5d8da9f89bfdcdf6e2ad31f0a309
# Parent  b3800429f5438857270cdbd72607da9f9da6daa9
Document invariants of AbstractControlFlowGraph.getBlocks().

diff -r b3800429f543 -r b07f96c783ad graal/com.oracle.graal.compiler.common/src/com/oracle/graal/compiler/common/cfg/AbstractControlFlowGraph.java
--- a/graal/com.oracle.graal.compiler.common/src/com/oracle/graal/compiler/common/cfg/AbstractControlFlowGraph.java	Mon Jul 14 19:55:14 2014 +0200
+++ b/graal/com.oracle.graal.compiler.common/src/com/oracle/graal/compiler/common/cfg/AbstractControlFlowGraph.java	Mon Jul 14 19:27:35 2014 +0200
@@ -29,12 +29,28 @@
     static final int BLOCK_ID_INITIAL = -1;
     static final int BLOCK_ID_VISITED = -2;
 
+    /**
+     * Returns the list blocks contained in this control flow graph.
+     *
+     * It is {@linkplain CFGVerifier guaranteed} that the blocks are numbered according to a reverse
+     * post order traversal of the control flow graph.
+     *
+     * @see CFGVerifier
+     */
     List<T> getBlocks();
 
     Collection<Loop<T>> getLoops();
 
     T getStartBlock();
 
+    /**
+     * Calculates the common dominator of two blocks.
+     *
+     * Note that this algorithm makes use of special properties regarding the numbering of blocks.
+     *
+     * @see #getBlocks()
+     * @see CFGVerifier
+     */
     public static AbstractBlock<?> commonDominator(AbstractBlock<?> a, AbstractBlock<?> b) {
         if (a == null) {
             return b;
@@ -55,6 +71,9 @@
         return iterA;
     }
 
+    /**
+     * @see AbstractControlFlowGraph#commonDominator(AbstractBlock, AbstractBlock)
+     */
     @SuppressWarnings("unchecked")
     public static <T extends AbstractBlock<T>> T commonDominatorTyped(T a, T b) {
         return (T) commonDominator(a, b);