Documented assembly and peephole phases

phases/assemble.mli

@@ -1 +1,16 @@
+(** Transform AST into assembly instructions. *)
+
+(** The AST has been simplified and annotated by earlier phases upto this point.
+    The assembly phase uses the annotations to generate a list of instructions
+    of type {!Types.instr}. For many instructions, a stringification of the
+    relevant AST nodes is added as a [Comment] or [InlineComment], so that the
+    programmer can line up assembly code with source code. This is especially
+    helpful when analysing larger programs and programs with language features
+    that generate a lot of code. E.g., for-loops that have been transformed into
+    while-loops can appear quite intimidating in uncommented assembly code.
+
+    The output of this phase is an [Assembly] intermediate type.
+    *)
+
+(** Main phase function, called by {!Main}. *)
 val phase : Main.phase_func

phases/peephole.mli

@@ -1 +1,41 @@
+(** Peephole optimisation on generated assembly. *)
+
+(** This is a final optimisation round that makes use of optimised VM
+    instructions and common optimisable constructions in generated assembly
+    code.
+
+    There are two optimisations on branch instructions: if the branch is never
+    taken, remove it. If the branch is always taken, replace it with a jump
+    instruction:
+{v     bloadc_t
+    branch_t label
+       OR
+    bloadc_f
+    branch_f label v}
+becomes [jump label].
+
+{v     bloadc_f
+    branch_t label
+       OR
+    bloadc_t
+    branch_f label v}
+    is removed.
+
+    The last performed optimisation is somewhat more complex, namely the
+    conversion of addition or subtraction of an integer variable by a constant
+    value, to specialised [iinc|idec] instructions:
+{v     iload L          |   iload L
+    iloadc[_ ]C      |   iloadc_1
+    i{add,sub}       |   i{add,sub}
+    istore L         |   istore L
+        |                    |
+        v                    v
+    i{inc,dec} L C   |   i{inc,dec}_1 L v}
+
+    Note that the [iload] and [iloadc] may also be in reverse order, which in
+    CiviC code is the difference between [i = i + 1;] and [i = 1 + i]. Both
+    orders of succession are supported by the implementation.
+    *)
+
+(** Main phase function, called by {!Main}. *)
 val phase : Main.phase_func