Add documentation.

Author: nicolasstucki

compiler/src/dotty/tools/dotc/core/PhantomErasure.scala

@@ -0,0 +1,28 @@
+package dotty.tools.dotc.core
+
+import dotty.tools.dotc.ast.tpd._
+import dotty.tools.dotc.core.Contexts.Context
+import dotty.tools.dotc.core.Symbols.defn
+import dotty.tools.dotc.core.Types.Type
+
+/** Phantom erasure erases (minimal erasure):
+ *
+ *  - Parameters/arguments are erased to BoxedUnit. The next step will remove the parameters
+ *    from the method definitions and calls (implemented in branch implement-phantom-types-part-2).
+ *  - Definitions of `def`, `val`, `lazy val` and `var` returning a phantom type to return a BoxedUnit. The next step
+ *    is to erase the fields for phantom types (implemented in branch implement-phantom-types-part-3)
+ *  - Calls to Phantom.assume become calls to BoxedUnit. Intended to be optimized away by local optimizations.
+ *
+ *  BoxedUnit is used as it fits perfectly and homogeneously in all locations where phantoms can be found.
+ *  Additionally some of the optimizations that can be performed on phantom types can also be directly implemented
+ *  on all boxed units.
+ */
+object PhantomErasure {
+
+  /** Returns the default erased type of a phantom type */
+  def erasedPhantomType(implicit ctx: Context): Type = defn.BoxedUnitType
+
+  /** Returns the default erased tree for a call to Phantom.assume */
+  def erasedAssume(implicit ctx: Context): Tree = ref(defn.BoxedUnit_UNIT)
+
+}

compiler/src/dotty/tools/dotc/core/TypeErasure.scala

@@ -364,7 +364,7 @@ class TypeErasure(isJava: Boolean, semiEraseVCs: Boolean, isConstructor: Boolean
       else if (semiEraseVCs && isDerivedValueClass(sym)) eraseDerivedValueClassRef(tp)
       else if (sym == defn.ArrayClass) apply(tp.appliedTo(TypeBounds.empty)) // i966 shows that we can hit a raw Array type.
       else if (defn.isSyntheticFunctionClass(sym)) defn.erasedFunctionType(sym)
-      else if (defn.isPhantomTerminalClass(tp.symbol)) defn.BoxedUnitType
+      else if (defn.isPhantomTerminalClass(tp.symbol)) PhantomErasure.erasedPhantomType
       else eraseNormalClassRef(tp)
     case tp: RefinedType =>
       val parent = tp.parent
@@ -404,6 +404,7 @@ class TypeErasure(isJava: Boolean, semiEraseVCs: Boolean, isConstructor: Boolean
             case tr :: trs1 =>
               assert(!tr.classSymbol.is(Trait), cls)
               val tr1 = if (cls is Trait) defn.ObjectType else tr
+              // We remove the Phantom trait to erase the definitions of Phantom.{assume, Any, Nothing}
               tr1 :: trs1.filterNot(x => x.isRef(defn.ObjectClass) || x.isRef(defn.PhantomClass))
             case nil => nil
           }
@@ -508,7 +509,7 @@ class TypeErasure(isJava: Boolean, semiEraseVCs: Boolean, isConstructor: Boolean
         if (defn.isSyntheticFunctionClass(sym))
           sigName(defn.erasedFunctionType(sym))
         else if (defn.isPhantomTerminalClass(tp.symbol))
-          sigName(defn.BoxedUnitType)
+          sigName(PhantomErasure.erasedPhantomType)
         else
           normalizeClass(sym.asClass).fullName.asTypeName
       case defn.ArrayOf(elem) =>

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -201,7 +201,7 @@ object Types {
       else defn.NothingType
     }
 
-    /** Returns the type of the lattice (i.e. the prefix of the phantom type)
+    /** Returns the type of the phantom lattice (i.e. the prefix of the phantom type)
       *   - XYZ if XYZ extends scala.Phantom and this type is upper bounded XYZ.Any
       *   - NoType otherwise
       */

compiler/src/dotty/tools/dotc/transform/Erasure.scala

@@ -23,7 +23,7 @@ import core.Decorators._
 import dotty.tools.dotc.ast.{Trees, tpd, untpd}
 import ast.Trees._
 import scala.collection.mutable.ListBuffer
-import dotty.tools.dotc.core.{Constants, Flags}
+import core.{Constants, Flags, Mode, PhantomErasure}
 import ValueClasses._
 import TypeUtils._
 import ExplicitOuter._
@@ -455,7 +455,7 @@ object Erasure extends TypeTestsCasts{
       if (fun.symbol == defn.cbnArg)
         typedUnadapted(args.head, pt)
       else if (fun.symbol eq defn.Phantom_assume)
-        ref(defn.BoxedUnit_UNIT)
+        PhantomErasure.erasedAssume
       else typedExpr(fun, FunProto(args, pt, this)) match {
         case fun1: Apply => // arguments passed in prototype were already passed
           fun1

compiler/src/dotty/tools/dotc/typer/Typer.scala

@@ -1348,6 +1348,7 @@ class Typer extends Namer with TypeAssigner with Applications with Implicits wit
           cls, isRequired, cdef.pos)
     }
 
+    // Check that phantom lattices are defined in an `object`
     if (cls.classParents.exists(_.classSymbol eq defn.PhantomClass)) {
       if (!cls.is(Module))
         ctx.error("Only object can extend scala.Phantom", cdef.pos)