Documented context analysis

phases/context.mli

@@ -1,3 +1,28 @@
-val phase : Main.phase_func
+(** Context analysis: find declarations of used variables and functions. *)
+
+(** The desugared CiviC code contains [Var], [FunCall] and [Assign] nodes. These
+    all use variables or functions identified by a [string] name. The context
+    analysis phase links each occurrence of this node to a declaration: a
+    [VarDec], [Param], [Dim], [GlobalDe[cf]] or [FunDe[cf]].  Since the original
+    nodes only have a [string] field to save the declaration, new node types
+    have been added which replace the name with a declaration node: [VarUse],
+    [FunUse], and [VarLet].
+
+    The phase traverses into functions, but first finds declarations in the
+    entire outer scope of the function, since functions can use any function of
+    variable that is defined within the same scope.
 
+    The whole analysis is done in one traversal. When a declaration node is
+    encountered, its name and declaration are added to the currect scope (a
+    mutable hash table). When a vairable of fuction use is encountered, the name
+    and declaration are looked up in the current scope. The scope is duplicated
+    when entering a function, and restored when exiting the function, so that
+    functions that are not subroutines of each other, do not share inner variable
+    definitions. *)
+
+(** Traversal that replaces names with declarations. Exported for use in other
+    phases. *)
 val analyse_context : Types.node -> Types.node
+
+(** Main phase function, called by {!Main}. Calls {!analyse_context}. *)
+val phase : Main.phase_func