Documented index analysis phase

phases/index.ml

@@ -1,6 +1,7 @@
 open Types
 open Util
 
+(* Tag declarations with stack frame indices *)
 let tag_index program =
   let nglobs = ref 0 in
   let nimport = ref 0 in
@@ -61,6 +62,7 @@ let tag_index program =
     | _ -> transform_children trav node
   in tag (ref 0) [] program
 
+(* Undo context analysis *)
 let rec strip_context = function
   | VarUse (dec, dims, ann) ->
     Var (nameof dec, optmap strip_context dims, ann)

phases/index.mli

@@ -1,5 +1,22 @@
-(**  *)
-val tag_index : Types.node -> Types.node
+(** Tag variable declarations with stack frame indices. *)
 
-(**  *)
+(** The assembly phase needs to know indices of variables in the current stack
+    frame to be pass to [load|store] instructions. This phase traverses the AST
+    and adds [Index] annotations based on a counter that is increased when
+    declaration is encountered.
+
+    A problem, however, is that uses of these declarations do not inherit these
+    annotations, since the declaration annotations are not references.
+    Therefore, this phase first strips all context analysis by replacing
+    variable/function uses with the original [Var|Assign|FunCall] nodes. Then,
+    index analysis is performed on declarations. Finally, the
+    {!Context.analyse_context} traversal is re-run to carry the [Index]
+    annotations to the variable/function uses.
+
+    Note that we can safely assume that no errors will occur during this context
+    analysis, since incorrect uses would have been spotted by the earlier
+    context analysis already.
+    *)
+
+(** Main phase function, called by {!Main}. *)
 val phase : Main.phase_func