Improve Simplify's documentation

Author: DarkDimius

compiler/src/dotty/tools/dotc/transform/localopt/BubbleUpNothing.scala

@@ -5,11 +5,19 @@ import core.Contexts.Context
 import core.Symbols._
 import ast.Trees._
 
-/** Every pure statement preceding a ??? can be removed.
+/**
+ * If a block has a statement that evaluates to Nothing:
+ *  - Every pure statement dirrectly preceding an expression that returns Nothing can be removed,
+ *  - as every statement after an expression that returns Nothing can be removed
+ *
+ * If an If condition evalutates to Nothing, the entire If can be replaced by condition
+ * If an argument evaluates to Nothing, the entire call can be replaced by evaluation of arguments.
  *
  *  This optimisation makes it rather tricky to write meaningful examples
  *  since the compiler will often be able to reduce them to a single main
  *  method with body = ???.
+ *
+ *  @author DarkDimius, OlivierBlanvillain
  */
 class BubbleUpNothing(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._

compiler/src/dotty/tools/dotc/transform/localopt/ConstantFold.scala

@@ -11,11 +11,14 @@ import Simplify.desugarIdent
 /** Various constant folding.
  *
  *  - Starts/ends with the constant folding implemented in typer (ConstFold).
- *
+ *  - Join branches if they are "similar"
+ *  - regularize arithmetic and boolean expressions to have constants on the left, ie. 6 * 2 * a * 5 => 60 * a
  *  - (if) specific optimisation that propagate booleans, negation, and factor
- *    out (nested) if with equivalent branches wrt to isSimilar (using &&,||).
+ *    out (nested) if with equivalent branches wrt to isSimilar (using &&,||).  Dark:   ping @OlivierBlanvillain, I didn't understand this
  *
  *  - Constant propagation over pattern matching.
+ *
+ *  @author DarkDimius, OlivierBlanvillain
  */
  class ConstantFold(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._

compiler/src/dotty/tools/dotc/transform/localopt/Devalify.scala

@@ -13,7 +13,13 @@ import config.Printers.simplify
 import Simplify.desugarIdent
 import transform.SymUtils._
 
-/** Inline vals */
+/** Inline vals and remove vals that are aliases to other vals
+ *
+ * Notion of alias is a by-value notion, so "good" casts are ignored.
+ *
+ * This phase has to be careful not to eliminate vals that are parts of other types
+ * @author DarkDimius, OlivierBlanvillain
+ * */
 class Devalify(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._
 

compiler/src/dotty/tools/dotc/transform/localopt/DropGoodCasts.scala

@@ -16,6 +16,8 @@ import transform.SymUtils._
  *
  *  - a.asInstanceOf[T] → a when we know that a: T
  *  - Simplify (a == null) and (a != null) when the result is statically known
+ *
+ *  @author DarkDimius, OlivierBlanvillain
  */
  class DropGoodCasts(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._

compiler/src/dotty/tools/dotc/transform/localopt/DropNoEffects.scala

@@ -11,7 +11,10 @@ import ast.Trees._
 import Simplify.desugarIdent
 
 /** Removes side effect free statements in blocks and Defdef.
+ *  Flattens blocks(except Closure-blocks)
  *  Note: BoxedUnit currently messes up this phase when run after erasure
+ *
+ *  @author DarkDimius, OlivierBlanvillain
  */
 class DropNoEffects(val simplifyPhase: Simplify)(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._

compiler/src/dotty/tools/dotc/transform/localopt/InlineCaseIntrinsics.scala

@@ -10,12 +10,15 @@ import core.Flags._
 import ast.Trees._
 import transform.SymUtils._
 import Simplify.desugarIdent
+import dotty.tools.dotc.ast.tpd
 
 /** Inline case class specific methods using desugarings assumptions.
  *
  *  Note: to run this optimisation after erasure one would need to specialize
  *  it for constructor with outer pointer and values classes. There is
  *  probably no need to run this more than once.
+ *
+ *  @author DarkDimius, OlivierBlanvillain
  */
 class InlineCaseIntrinsics(implicit val ctx: Context) extends Optimisation {
   import ast.tpd._

compiler/src/dotty/tools/dotc/transform/localopt/RemoveUnnecessaryNullChecks.scala

@@ -40,7 +40,6 @@ import scala.collection.mutable
   val visitor: Tree => Unit = {
     case vd: ValDef =>
       val rhs = vd.rhs
-      val rhsName = rhs.symbol.name
       if (!vd.symbol.is(Mutable) && !rhs.isEmpty) {
         def checkNonNull(t: Tree, target: Symbol): Boolean = t match {
           case Block(_ , expr) =>

compiler/src/dotty/tools/dotc/transform/localopt/Simplify.scala

@@ -14,12 +14,24 @@ import ast.tpd
  *
  *  The termination condition uses referential equality on Trees. Furthermore,
  *  termination relies of every optimisation to be shrinking transformations.
+ *
+ *  This phase is intended to be run multiple times in the compilation pipeline.
+ *  This is due to several reasons:
+ *   - running this phase early allows to reduce size of compilation unit, speeding up subsequent transformations.
+ *   - running this phase late allows to eliminate inefficiencies created by previous phase
+ *   - different patters are easier to optimize at different moments of pipeline
  */
 class Simplify extends MiniPhaseTransform with IdentityDenotTransformer {
   import tpd._
   override def phaseName: String = "simplify"
   override val cpy = tpd.cpy
 
+  /** The original intention is to run most optimizations both before and after erasure.
+   * Erasure creates new inefficiencies as well as new optimization opportunities.
+   *
+   * The order of optimizations is tuned to converge faster.
+   * Reordering them may require quadratically more rounds to finish.
+   */
   private def beforeErasure(implicit ctx: Context): List[Optimisation] =
     new InlineCaseIntrinsics        ::
     new RemoveUnnecessaryNullChecks ::
@@ -36,6 +48,7 @@ class Simplify extends MiniPhaseTransform with IdentityDenotTransformer {
     new ConstantFold                ::
     Nil
 
+  /** see comment on  beforeErasure */
   private def afterErasure(implicit ctx: Context): List[Optimisation] =
     new Valify(this)                ::
     new Devalify                    ::

compiler/src/dotty/tools/dotc/transform/localopt/Varify.scala

@@ -11,6 +11,7 @@ import scala.collection.mutable
  *
  *  {
  *    val l = <expr>
+ *    // code that may use l
  *    var r = l
  *    // code not using l
  *  }
@@ -19,6 +20,7 @@ import scala.collection.mutable
  *
  *  {
  *    var r = <expr>
+ *    // code that may use l
  *    // code not using l
  *  }
  */