Scope docs (#99)

* More scope docs

* readme updates

1 files changed, 6 insertions, 5 deletions

diff --git a/chapter03/src/main/java/com/seaofnodes/simple/node/ScopeNode.java b/chapter03/src/main/java/com/seaofnodes/simple/node/ScopeNode.java
index e9ff0f44..379ef033 100644
--- a/chapter03/src/main/java/com/seaofnodes/simple/node/ScopeNode.java
+++ b/chapter03/src/main/java/com/seaofnodes/simple/node/ScopeNode.java
@@ -7,11 +7,12 @@ import java.util.*;
 /**
  * The Scope node is purely a parser helper - it tracks names to nodes with a
  * stack of scopes.
+ * @see <a href="file:../../../../../../../../chapter03/README.md">chapter03/README.md</a>
  */
 public class ScopeNode extends Node {
 
     /**
-     * Names for every input edge
+     * A Stack of symbol tables; a symbol table is a map from names to node indices.
      */
     public final Stack<HashMap<String, Integer>> _scopes;
 
@@ -48,7 +49,7 @@ public class ScopeNode extends Node {
      * Recover the names for all variable bindings.
      * The result is an array of names that is aligned with the
      * inputs to the Node.
-     *
+     * <p>
      * This is an expensive operation.
      */
     public String[] reverseNames() {
@@ -77,21 +78,21 @@ public class ScopeNode extends Node {
     }
     /**
      * Lookup a name in all scopes starting from most deeply nested.
-     *
+     * <p>
      * @param name Name to be looked up
      * @see #update(String, Node, int)
      */
     public Node lookup( String name ) { return update(name,null,_scopes.size()-1);  }
     /**
      * If the name is present in any scope, then redefine else null
-     *
+     * <p>
      * @param name Name being redefined
      * @param n    The node to bind to the name
      */
     public Node update( String name, Node n ) { return update(name,n,_scopes.size()-1); }
     /**
      * Both recursive lookup and update.
-     *
+     * <p>
      * A shared implementation allows us to create lazy phis both during
      * lookups and updates; the lazy phi creation is part of chapter 8.
      *