Address review and add docs

Author: liufengyun

compiler/src/dotty/tools/dotc/transform/init/Checking.scala

@@ -20,7 +20,7 @@ import Effects._, Potentials._, Summary._, Util._
 object Checking {
   /** The checking state
    *
-   *  Why `visited` is a set of `MethodCall` instead of `Symbol`? Think the following program:
+   *  Why `visited` is a set of effects instead of `Symbol`? Think the following program:
    *
    *      class C(x: Int, a: A @cold) {
    *        val n = if (x > 0) new C(x - 1, a).m() else 0
@@ -84,22 +84,17 @@ object Checking {
           val (pots, effs) = Summarization.analyze(vdef.rhs)(theEnv.withOwner(vdef.symbol))
           theEnv.summaryOf(cls).cacheFor(vdef.symbol, (pots, effs))
           if (!vdef.symbol.is(Flags.Lazy)) {
-            checkEffects(effs)
+            checkEffectsIn(effs, cls)
             traceIndented(vdef.symbol.show + " initialized", init)
             state.fieldsInited += vdef.symbol
           }
 
         case tree =>
           val (_, effs) = Summarization.analyze(tree)
-          checkEffects(effs)
+          checkEffectsIn(effs, cls)
       }
     }
 
-    def checkEffects(effs: Effects): Unit = {
-      val rebased = Effects.asSeenFrom(effs, ThisRef(state.thisClass)(null), cls, Potentials.empty)
-      rebased.foreach { check(_) }
-    }
-
     // check parent calls : follows linearization ordering
     // see spec 5.1 about "Template Evaluation".
     // https://www.scala-lang.org/files/archive/spec/2.13/05-classes-and-objects.html
@@ -159,8 +154,7 @@ object Checking {
 
     (stats :+ expr).foreach { stat =>
       val (_, effs) = Summarization.analyze(stat)(theEnv.withOwner(ctor))
-      val rebased = Effects.asSeenFrom(effs, ThisRef(state.thisClass)(null), cls, Potentials.empty)
-      rebased.foreach { check(_) }
+      checkEffectsIn(effs, cls)
     }
   }
 
@@ -183,6 +177,11 @@ object Checking {
       source.sourcePos
     )
 
+  private def checkEffectsIn(effs: Effects, cls: ClassSymbol)(implicit state: State): Unit = {
+    val rebased = Effects.asSeenFrom(effs, ThisRef(state.thisClass)(null), cls, Potentials.empty)
+    rebased.foreach { check(_) }
+  }
+
   private def check(eff: Effect)(implicit state: State): Unit =
     if (!state.visited.contains(eff)) traceOp("checking effect " + eff.show, init) {
       implicit val state2: State = state.withVisited(eff)
@@ -317,8 +316,8 @@ object Checking {
       }
     }
 
-  private def expand(pot: Potential)(implicit state: State): Potentials =
-    trace("expand " + pot.show, init, pots => Potentials.show(pots.asInstanceOf[Potentials])) { pot match {
+  private def expand(pot: Potential)(implicit state: State): Potentials = trace("expand " + pot.show, init, pots => Potentials.show(pots.asInstanceOf[Potentials])) {
+    pot match {
       case MethodReturn(pot1, sym) =>
         pot1 match {
           case thisRef @ ThisRef(cls) =>

compiler/src/dotty/tools/dotc/transform/init/Effects.scala

@@ -18,24 +18,38 @@ object Effects {
   def show(effs: Effects)(implicit ctx: Context): String =
     effs.map(_.show).mkString(", ")
 
+  /** Effects that are related to safe initialization */
   sealed trait Effect {
     def size: Int
     def show(implicit ctx: Context): String
     def source: Tree
   }
 
+  /** An effect means that a value that's possibly under initialization
+   *  leaks from the initializing world to fully-initialized world.
+   *
+   *  Essentially, this effect enforces that the object pointed to by
+   *  `potential` is fully initialized.
+   *
+   *  This effect is trigger in several scenarios:
+   *  - a potential is used as arguments to method calls or new-expressions
+   *  - a potential is assigned (not initialize) to a field
+   *  - the selection chain on a potential is too long
+   */
   case class Leak(potential: Potential)(val source: Tree) extends Effect {
     def size: Int = potential.size
     def show(implicit ctx: Context): String =
       potential.show + "↑"
   }
 
+  /** Field access, `a.f` */
   case class FieldAccess(potential: Potential, field: Symbol)(val source: Tree) extends Effect {
     def size: Int = potential.size
     def show(implicit ctx: Context): String =
       potential.show + "." + field.name.show + "!"
   }
 
+  /** Method call, `a.m()` */
   case class MethodCall(potential: Potential, method: Symbol)(val source: Tree) extends Effect {
     def size: Int = potential.size
     def show(implicit ctx: Context): String = potential.show + "." + method.name.show + "!"

compiler/src/dotty/tools/dotc/transform/init/Potentials.scala

@@ -20,12 +20,14 @@ object Potentials {
   def show(pots: Potentials)(implicit ctx: Context): String =
     pots.map(_.show).mkString(", ")
 
+  /** A potential represents an aliasing of a value that is possibly under initialization */
   sealed trait Potential {
     def size: Int
     def show(implicit ctx: Context): String
     def source: Tree
   }
 
+  /** The object pointed by `C.this` */
   case class ThisRef(classSymbol: ClassSymbol)(val source: Tree) extends Potential {
     val size: Int = 1
     def show(implicit ctx: Context): String = classSymbol.name.show + ".this"
@@ -50,6 +52,7 @@ object Potentials {
     }
   }
 
+  /** The object pointed by `C.super.this`, mainly used for override resolution */
   case class SuperRef(pot: Potential, supercls: ClassSymbol)(val source: Tree) extends Potential {
     val size: Int = 1
     def show(implicit ctx: Context): String = pot.show + ".super[" + supercls.name.show + "]"
@@ -113,21 +116,25 @@ object Potentials {
     def show(implicit ctx: Context): String = "Outer[" + pot.show + ", " + classSymbol.show + "]"
   }
 
+  /** The object pointed by `this.f` */
   case class FieldReturn(potential: Potential, field: Symbol)(val source: Tree) extends Potential {
     def size: Int = potential.size + 1
     def show(implicit ctx: Context): String = potential.show + "." + field.name.show
   }
 
+  /** The object returned by `this.m()` */
   case class MethodReturn(potential: Potential, symbol: Symbol)(val source: Tree) extends Potential {
     def size: Int = potential.size + 1
     def show(implicit ctx: Context): String = potential.show + "." + symbol.name.show
   }
 
+  /** The object whose initialization status is unknown */
   case class Cold()(val source: Tree) extends Potential {
     def size: Int = 1
     def show(implicit ctx: Context): String = "Cold"
   }
 
+  /** A function when called will produce the `effects` and return the `potentials` */
   case class Fun(potentials: Potentials, effects: Effects)(val source: Tree) extends Potential {
     def size: Int = 1
     def show(implicit ctx: Context): String =