Explain both level avoidance schemes in the TypeVar doc comment

scala · Aug 18, 2022 · 4649fd9 · 4649fd9
1 parent d44cbab
commit 4649fd9
Showing 1 changed file with 15 additions and 3 deletions.
diff --git a/compiler/src/dotty/tools/dotc/core/Types.scala b/compiler/src/dotty/tools/dotc/core/Types.scala
@@ -4501,9 +4501,21 @@ object Types {
    *  @param  creatorState  The typer state in which the variable was created.
    *  @param  nestingLevel  Symbols with a nestingLevel strictly greater than this
    *                        will not appear in the instantiation of this type variable.
-   *                        This is enforced in `ConstraintHandling#fixLevels`.
-   *                        The `nestingLevel` of a type variable can be made smaller when
-   *                        fixing the levels for some other type variable instance.
+   *                        This is enforced in `ConstraintHandling`, dependig on the
+   *                        Config flags setting `checkLevelsOnConstraints` and
+   *                        `checkLevelsOnInstantiation`.
+   *
+   *                        Under `checkLevelsOnConstraints` we maintain the invariant that
+   *                        the `nonParamBounds` of a type variable never refer to a type with a
+   *                        greater `nestingLevel` (see `legalBound` for the reason why this
+   *                        cannot be delayed until instantiation). Then, on instantiation,
+   *                        we replace any param in the param bound with a level greater than
+   *                        nestingLevel (see `fullLowerBound`).
+   *
+   *                        Under `checkLevelsOnInstantiation`, we avoid incorrect levels only
+   *                        when a type variable is instantiated, see `ConstraintHandling$fixLevels`.
+   *                        Under this mode, the `nestingLevel` of a type variable can be made
+   *                        smaller when fixing the levels for some other type variable instance.
    */
   final class TypeVar private(initOrigin: TypeParamRef, creatorState: TyperState | Null, var nestingLevel: Int) extends CachedProxyType with ValueType {
     private var currentOrigin = initOrigin