Merge pull request #292 from UQ-PAC/mra-docs

Add more docs to GRA, MRA and ReachingDefinitionsAnalysis

src/main/scala/analysis/GlobalRegionAnalysis.scala

@@ -5,6 +5,17 @@ import ir.*
 
 import scala.collection.mutable
 
+/** Identifies global data regions.
+ *
+ * This is iterated until results reach a fixpoint.
+ *
+ * @param program
+ * @param domain reachable parts of the program
+ * @param constantProp constant propagation results
+ * @param reachingDefs maps each CFG node to two maps: variable definitions and variables uses.
+ * @param mmm preloaded globals from symbol table.
+ * @param vsaResult extra information from VSA results of previous passes.
+ */
 trait GlobalRegionAnalysis(
   val program: Program,
   val domain: Set[CFGPosition],

src/main/scala/analysis/MemoryRegionAnalysis.scala

@@ -8,6 +8,19 @@ import util.Logger
 import scala.collection.mutable
 import scala.collection.mutable.ListBuffer
 
+/** Identifies stack and heap regions.
+ *
+ * This is iterated until results reach a fixpoint.
+ * Subsequent runs may refine the definition of global data regions as well.
+ *
+ * @param program
+ * @param domain reachable parts of the program
+ * @param constantProp constant propagation results
+ * @param reachingDefs maps each CFG node to two maps: variable definitions and variables uses.
+ * @param graResult results from global region analysis.
+ * @param mmm preloaded globals from symbol table.
+ * @param vsaResult extra information from VSA results of previous passes.
+ */
 trait MemoryRegionAnalysis(
   val program: Program,
   val domain: Set[CFGPosition],

src/main/scala/analysis/ReachingDefinitionsAnalysis.scala

@@ -6,6 +6,7 @@ import analysis.solvers.SimpleWorklistFixpointSolver
 type ReachingDefTuple =
   TupleLattice[MapLattice[Variable, Set[Assign], PowersetLattice[Assign]], MapLattice[Variable, Set[Assign], PowersetLattice[Assign]], Map[Variable, Set[Assign]], Map[Variable, Set[Assign]]]
 
+/** Calculates def-use chains for the program. */
 trait ReachingDefinitionsAnalysis(program: Program) {
 
   private val tupleLattice: TupleLattice[MapLattice[Variable, Set[Assign], PowersetLattice[Assign]], MapLattice[Variable, Set[Assign], PowersetLattice[