Add scaladoc on expression compiler phases

Author: adpi2

compiler/src/dotty/tools/debug/ExtractExpression.scala

@@ -17,7 +17,55 @@ import dotty.tools.dotc.report
 import dotty.tools.dotc.util.SrcPos
 import scala.annotation.nowarn
 
-private class ExtractExpression(config: ExpressionCompilerConfig, expressionStore: ExpressionStore) extends MacroTransform with DenotTransformer:
+/**
+  * This phase extracts the typed expression from the source tree, transfoms it and places it
+  * in the evaluate method of the Expression class.
+  * 
+  * Before:
+  *   package example:
+  *     class A:
+  *       def m: T =
+  *         val expression =
+  *           println("")
+  *           typed_expr
+  *         body
+  *     
+  *     class Expression(thisObject: Any, names: Array[String], values: Array[Any]):
+  *       def evaluate(): Any = ()
+  * 
+  * After:
+  *   package example:
+  *     class A:
+  *       def m: T = body
+  *     
+  *     class Expression(thisObject: Any, names: Array[String], values: Array[Any]):
+  *       def evaluate(): Any = 
+            {
+  *           transformed_expr
+  *         }
+  * 
+  * Every access to a local variable, or an inaccessible member is transformed into a temporary reflectEval call.
+  * A ReflectEvalStrategy is attached to each reflectEval call to describe what should be evaluated and how.
+  * When printing trees for debugging, the ReflectEvalStrategy appears as a String literal argument.
+  * 
+  * Examples:
+  *
+  * 1. Get local variable `a`:
+  *      reflectEval(null, "ReflectEvalStrategy.LocalValue(a)", [])
+  * 
+  * 2. Call private method `a.m(x1, x2)`:
+  *      reflectEval(a, "ReflectEvalStrategy.MethodCall(m)", [x1, x2])
+  *
+  * 3. Set private field `a.b = c`:
+  *      reflectEval(a, "ReflectEvalStrategy.FieldAssign(b)", [c])
+  * 
+  * etc
+  *
+  */
+private class ExtractExpression(
+    config: ExpressionCompilerConfig,
+    expressionStore: ExpressionStore
+) extends MacroTransform with DenotTransformer:
   override def phaseName: String = ExtractExpression.name
 
   /** Update the owner of the symbols inserted into `evaluate`. */

compiler/src/dotty/tools/debug/InsertExpression.scala

@@ -18,9 +18,28 @@ import dotty.tools.io.VirtualFile
 import java.nio.charset.StandardCharsets
 
 /**
- * This phase inserts the expression being evaluated at the line of the breakpoint
- * and inserts the expression class in the same package (so that it can access package private symbols)
- */
+  * This phase inserts the expression being evaluated at the line of the breakpoint
+  * and inserts the expression class in the same package (so that it can access package private symbols).
+  * 
+  * Before:
+  *   package example:
+  *     class A:
+  *       def m: T =
+  *         body // breakpoint here
+  * 
+  * After:
+  *   package example:
+  *     class A:
+  *       def m: T =
+  *         val expression =
+  *           println("") // effect, to prevent constant-folding
+  *           expr        // inserted expression
+  *         body          // breakpoint here
+  *     
+  *     class Expression(thisObject: Any, names: Array[String], values: Array[Any]):
+  *       def evaluate(): Any = ()
+  * 
+  */
 private class InsertExpression(config: ExpressionCompilerConfig) extends Phase:
   private var expressionInserted = false
 

compiler/src/dotty/tools/debug/ResolveReflectEval.scala

@@ -16,6 +16,22 @@ import dotty.tools.dotc.report
 import dotty.tools.dotc.transform.MegaPhase.MiniPhase
 import dotty.tools.dotc.transform.ValueClasses
 
+/**
+  * This phase transforms every reflectEval call to an actual method call that performs reflection.
+  * Specifically it does:
+  *   - encode symbols to Java
+  *   - box and unbox value classes where necessary
+  *   - box and unbox captured variables where necessary
+  *   - evaluate by-name params where necessary
+  *   - resolve captured variables and check they are available (they may not be captured at runtime)
+  * 
+  * Before:
+  *   this.reflectEval(a, "ReflectEvalStrategy.MethodCall(m)", args)
+  * 
+  * After:
+  *   this.callMethod(a, "example.A", "m", ["ArgType1", "ArgType2"], "ResType", args)
+  *
+  */ 
 private class ResolveReflectEval(config: ExpressionCompilerConfig, expressionStore: ExpressionStore) extends MiniPhase:
   private val reflectEvalName = termName("reflectEval")
   private val elemName = termName("elem")