--- a/src/main/scala/SparqlToSparql.scala	Thu May 20 12:55:21 2010 +0200
+++ b/src/main/scala/SparqlToSparql.scala	Tue Jun 08 17:01:53 2010 -0400
@@ -10,6 +10,10 @@
 import w3c.sw.sparql
 
 object SparqlToSparql {
+
+  /**
+   * Some tools for making pretty output, e.g. shortening strings.
+   */
   var RuleLabels = scala.collection.mutable.Map[String,String]()
   var Abbreviations = scala.collection.mutable.Map[String,String]()
   def _shorten (s:String) = {
@@ -19,6 +23,10 @@
     s3
   }
 
+
+  /**
+   * Substitute the terms in a triple pattern or a graph pattern with other terms.
+   */
   def substituteTerm (changeMe:sparql.Term, from:sparql.Term, to:sparql.Term):sparql.Term = {
     if (changeMe == from) to
     else changeMe
@@ -41,12 +49,18 @@
   type VarMap = Map[sparql.Var, sparql.Term]
 
   def substituteGraphPattern (gp:sparql.GraphPattern, vartermmap:VarMap, varPrefix:String):sparql.GraphPattern = {
+    /**
+     * Substitute gp (the rule body) with the variables and constants from the
+     * query which matched variables in the rule head.
+     */
     val mapped = vartermmap.foldLeft(gp)((incrementalGP, varterm) => {
       val (varr, term) = varterm
       substitute(incrementalGP, sparql.TermVar(varr), term)
     })
 
-    /* "Uniquely" prefix unmapped vars to void conflict with other rules. */
+    /**
+     * "Uniquely" prefix unmapped vars to void conflict with other rules.
+     */
     // val bound = Set[sparql.Var](vartermmap.map((varterm) => varterm._1))
     val bound = vartermmap.foldLeft(Set[sparql.Var]())((s, varterm) => s + varterm._1)
     val mappedTo = vartermmap.foldLeft(Set[sparql.Term]())((s, varterm) => s + varterm._2)
@@ -62,6 +76,12 @@
       substitute(substitute(construct.gp, trigger.s, tp.s), trigger.o, tp.o)
     }
   }
+
+  /**
+   * Bindings keep track of all the ways that a particular rule has been invoked
+   * in order to cover a particular query pattern. It's a mapping from a rule to
+   * the list of "editions" (invocations) of that rule.
+   */
   case class Bindings (b:Map[sparql.Construct, List[VarMap]]) {
     def countEditions () = {
       var count = 0
@@ -96,6 +116,9 @@
 	}) + ")"
       }).mkString("\n    ", ",\n    ", "") + ")"
     }).mkString("\n  ", ",\n  ", "") + "))"
+    /**
+     * Make sure a particular rule has an entry in the Bindings.
+     */
     def ensureGraphPattern (construct:sparql.Construct) = {
       if (b.contains(construct)) this
       else Bindings(b + (construct -> List[VarMap]()))
@@ -173,6 +196,10 @@
   def createEmptyBindings () = Bindings(Map[sparql.Construct, List[VarMap]]())
 
   case class RuleMap (rules:Map[sparql.Uri, List[RuleIndex]]) {
+    /**
+     * Recursively examine the first triple pattern in a graph pattern and add
+     * invocations to the bindings to produce that triple.
+     */
     def transform (prove:List[sparql.TriplePattern], used:Set[sparql.TriplePattern], varsP:Bindings):Bindings = {
       val _pad = used.foldLeft("")((s, x) => s + " ")
       def _deepPrint (s:String):Unit = {