add tons of documentation

Author: Linyxus

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

@@ -25,6 +25,8 @@ sealed abstract class GadtConstraint extends Showable {
   /** Immediate bounds of a path-dependent type.
     * This variant of bounds will ONLY try to retrieve path-dependent GADT bounds. */
   def bounds(path: PathType, sym: Symbol)(using Context): TypeBounds | Null
+
+  /** Immediate bounds of path-dependent type tp. */
   def bounds(tp: TypeRef)(using Context): TypeBounds | Null
 
   /** Full bounds of `sym`, including TypeRefs to other lower/upper symbols.
@@ -34,7 +36,10 @@ sealed abstract class GadtConstraint extends Showable {
    */
   def fullBounds(sym: Symbol)(using Context): TypeBounds | Null
 
+  /** Full bounds of path dependent type path.sym. */
   def fullBounds(path: PathType, sym: Symbol)(using Context): TypeBounds | Null
+
+  /** Full bounds of path-dependent type tp. */
   def fullBounds(tp: TypeRef)(using Context): TypeBounds | Null
 
   /** Is `sym1` ordered to be less than `sym2`? */
@@ -65,7 +70,10 @@ sealed abstract class GadtConstraint extends Showable {
   /** Check whether two paths are equivalent via path aliasing. */
   def isAliasingPath(p: PathType, q: PathType): Boolean
 
-  /** Scrutinee path of the current pattern matching. */
+  /** Scrutinee path of the current pattern matching that is being typed.
+    *
+    * See `constrainTypeMembers` in `PatternTypeConstrainer`.
+    */
   def scrutineePath: TermRef | Null
 
   /** Reset scrutinee path to null. */
@@ -74,10 +82,16 @@ sealed abstract class GadtConstraint extends Showable {
   /** Set the scrutinee path. */
   def withScrutineePath[T](path: TermRef | Null)(op: => T): T
 
-  /** Supply the real pattern path. */
+  /** Supply the real pattern path.
+    *
+    * See `constrainTypeMembers` in `PatternTypeConstrainer`.
+    */
   def supplyPatternPath(path: TermRef)(using Context): Unit
 
-  /** Create a skolem type for pattern. */
+  /** Create a skolem type for pattern and save it in the constraint handler.
+    *
+    * See `constrainTypeMembers` in `PatternTypeConstrainer`.
+    */
   def createPatternSkolem(pat: Type): SkolemType
 
   /** Is the symbol registered in the constraint?
@@ -95,6 +109,7 @@ sealed abstract class GadtConstraint extends Showable {
   /** Checks whether a given path-dependent type is constrainable. */
   def isConstrainablePDT(path: PathType, sym: Symbol)(using Context): Boolean
 
+  /** Get all type members registered in the constraint handler for this path. */
   def registeredTypeMembers(path: PathType): List[Symbol]
 
   /** GADT constraint narrows bounds of at least one variable */

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

@@ -201,6 +201,7 @@ trait PatternTypeConstrainer { self: TypeComparer =>
       *
       * To inference SR constraints for the type members from the scrutinee `p` and the pattern `q`,
       * we first find all the abstract type members of `p`: A₁, A₂, ⋯, Aₖ.
+      * If these path-dependent types are not registered in the handler, we will register them.
       *
       * Then, for each Aᵢ, if `q` also has a type member labaled `Aᵢ`, we inference SR constraints by calling
       * TypeComparer on the relation `p.Aᵢ <:< q.Aᵢ`.
@@ -209,12 +210,12 @@ trait PatternTypeConstrainer { self: TypeComparer =>
       * Specially, if for some `Aᵢ`, `p.Aᵢ` is abstract while `q.Aᵢ` is not, we will extract constraints
       * for both directions of the subtype relations (i.e. both `p.Aᵢ <:< q.Aᵢ` and `q.Aᵢ <:< p.Aᵢ`).
       *
-      * How we find out and handle the path (`TermRef`) of the scrutinee and pattern.
+      * How we find out and handle the path (`TermRef`) of the scrutinee and pattern:
       *
-      * - The path of scrutinee is not directly available in `constrainPatternType`, since the scrutinee type
-      *   passed to this function is widened.
-      *   To make the path available during GADT reasoning, we save the scrutinee path in `Typer.typedCase`. The scrutinee path will be saved in `ctx.gadt.scrutineePath`.
-      *   Note that we have to clear the saved scrutinee path after using by calling `ctx.gadt.resetScrutineePath()`.
+      * - The path of scrutinee is not directly available in `constrainPatternType`, since the scrutinee type passed to this function is widened.
+      *   To have access to the scrutinee path here, we save the scrutinee path in `Typer.typedCase` with `GadtConstraint.withScrutineePath`,
+      *   and the scrutinee path will be accessible as `ctx.gadt.scrutineePath`.
+      *   Note that we have to reset the saved scrutinee path to `null` after using by calling `ctx.gadt.resetScrutineePath()`.
       *   This is because `constrainPatternType` may be called multiple times for one nested pattern. For example:
       *
       *     e match
@@ -230,7 +231,7 @@ trait PatternTypeConstrainer { self: TypeComparer =>
       import NameKinds.DepParamName
       val realScrutineePath = ctx.gadt.scrutineePath
 
-      /* We reset scrutinee path so that the path will only be used at top level. */
+      // We reset scrutinee path so that the path will only be used at top level.
       ctx.gadt.resetScrutineePath()
 
       val saved = state.nn.constraint
@@ -242,8 +243,9 @@ trait PatternTypeConstrainer { self: TypeComparer =>
       val patternPath: SkolemType = ctx.gadt.createPatternSkolem(pat)
 
       val registerScrutinee = ctx.gadt.contains(scrutineePath) || ctx.gadt.addToConstraint(scrutineePath)
-      val registerPattern = ctx.gadt.addToConstraint(patternPath)   // Pattern path is a freshly-created skolem,
-                                                                    // so it will always be un-registered at this point
+      // Pattern path is a freshly-created skolem,
+      // so it will always be un-registered at this point
+      val registerPattern = ctx.gadt.addToConstraint(patternPath)
 
       /** Reconstruct subtype constraints for a path `p`, given that `p` and `q`
         are cohabitated.
@@ -260,7 +262,7 @@ trait PatternTypeConstrainer { self: TypeComparer =>
 
         (3) q.T is unregistered. We will do SR on p.T <:< q.T and q.T <:< p.T.
       */
-      def reconstructSubTypeFor(p: PathType, q: PathType) =
+      def reconstructSubType(p: PathType, q: PathType) =
         def processMember(sym: Symbol): Boolean =
           q.member(sym.name).isInstanceOf[NoDenotation.type] || {
             val pType = TypeRef(p, sym)
@@ -281,8 +283,8 @@ trait PatternTypeConstrainer { self: TypeComparer =>
       def constrainPattern: Boolean = {
         ctx.gadt.recordPathAliasing(scrutineePath, patternPath)
 
-        (!registerPattern || reconstructSubTypeFor(patternPath, scrutineePath))
-        && (!registerScrutinee || reconstructSubTypeFor(scrutineePath, patternPath))
+        (!registerPattern || reconstructSubType(patternPath, scrutineePath))
+        && (!registerScrutinee || reconstructSubType(scrutineePath, patternPath))
       }
 
       /** Reconstruct subtype when the pattern is an alias to another path.
@@ -299,8 +301,8 @@ trait PatternTypeConstrainer { self: TypeComparer =>
           val registerPtPath = ctx.gadt.contains(ptPath) || ctx.gadt.addToConstraint(ptPath)
 
           val result =
-            (!registerPtPath || reconstructSubTypeFor(ptPath, scrutineePath))
-            && (!registerScrutinee || reconstructSubTypeFor(scrutineePath, ptPath))
+            (!registerPtPath || reconstructSubType(ptPath, scrutineePath))
+            && (!registerScrutinee || reconstructSubType(scrutineePath, ptPath))
 
           ctx.gadt.recordPathAliasing(scrutineePath, ptPath)
 

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

@@ -1755,18 +1755,36 @@ class Typer(@constructorOnly nestingLevel: Int = 0) extends Namer
         case p: TermRef =>
           tree.pat match {
             case _: (Trees.Typed[_] | Trees.Ident[_] | Trees.Apply[_] | Trees.Bind[_]) =>
+              // We only record scrutinee path in the above cases, b/c recording
+              // it in all cases may lead to unsoundness.
+              //
+              // For example:
+              //
+              //  def foo(e: (Expr, Expr)) = e match
+              //    case (e1: Expr, e2: Expr) =>
+              //
+              // Here the pattern is a tuple. `constrainPatternType` will be called
+              // on the two elements of the tuple directly, without constraining
+              // `e` and the whole tuple first.
+              // Therefore, recording the scrutinee path in this case can give
+              // us constraints like `e1.type == e.type`, which is not true.
               p
             case _ =>
               null
           }
         case _ => null
       }
 
+    // Save the scrutinee path and then type the pattern.
+    // The scrutinee path will be used in SR reasoning for path-dependent types.
+    // See `constrainTypeMembers` in `PatternTypeConstrainer`.
     val pat1 = gadtCtx.gadt.withScrutineePath(scrutineePath) {
       typedPattern(tree.pat, wideSelType)(using gadtCtx)
     }
 
     if scrutineePath.ne(null) && pat1.symbol.isPatternBound then
+      // Subtitute the place holder with real pattern path in GADT constraints.
+      // See `constrainTypeMembers` in `PatternTypeConstrainer`.
       gadtCtx.gadt.supplyPatternPath(pat1.symbol.termRef)
 
     caseRest(pat1)(