Update doc

Author: noti0na1

compiler/src/dotty/tools/dotc/ast/tpd.scala

@@ -939,6 +939,8 @@ object tpd extends Trees.Instance[Type] with TypedTreeInfo {
     def appliedToTypeTrees(targs: List[Tree])(using Context): Tree =
       if targs.isEmpty then tree else
         val app = TypeApply(tree, targs)
+        // If unsafe-nulls is enabled, a key is added to the Tree.
+        // So a relaxed bound check can be used for these types In PostTyper.
         app.putAttachment(Nullables.UnsafeNullsKey, config.Feature.unsafeNullsEnabled)
         app
 

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

@@ -123,6 +123,9 @@ object Mode {
   /** Should we try to convert values ignoring Null type? */
   val UnsafeNullConversion: Mode = newMode(28, "UnsafeNullConversion")
 
-  /** Unsafe Nulls SubType */
+  /** Should we use Unsafe Nulls SubTyping in TypeComparer?
+   *  If this mode is in the Context, `Null` is considered as a
+   *  subtype of all reference type.
+   */
   val UnsafeNullsSubType: Mode = newMode(29, "UnsafeNullsSubType")
 }

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

@@ -1082,6 +1082,8 @@ trait Applications extends Compatibility {
         if (typedFn.tpe eq TryDynamicCallType) tryDynamicTypeApply()
         else assignType(cpy.TypeApply(tree)(typedFn, typedArgs), typedFn, typedArgs)
     }
+    // If unsafe-nulls is enabled, a key is added to the Tree.
+    // So a relaxed bound check can be used for these types In PostTyper.
     app.putAttachment(Nullables.UnsafeNullsKey, config.Feature.unsafeNullsEnabled)
     app
   }

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

@@ -49,6 +49,8 @@ object Nullables:
 
   /** A StickyKey for TypeApply and AppliedType in unsafe nulls,
    *  In PostTyper, a relaxed bound check is used for these types.
+   *  Since we are unable to track `unsafeNulls` after Typer, this
+   *  key is necessary.
    */
   val UnsafeNullsKey = Property.StickyKey[Boolean]
 

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

@@ -778,6 +778,7 @@ class Typer extends Namer
         // A sequence argument `xs: _*` can be either a `Seq[T]` or an `Array[_ <: T]`,
         // irrespective of whether the method we're calling is a Java or Scala method,
         // so the expected type is the union `Seq[T] | Array[_ <: T]`.
+        // If unsafe nulls is enabled, the expected type is `Seq[T | Null] | Array[_ <: T | Null] | Null`.
         val ptArg =
           // FIXME(#8680): Quoted patterns do not support Array repeated arguments
           if (ctx.mode.is(Mode.QuotedPattern))
@@ -796,8 +797,10 @@ class Typer extends Namer
         val expr0 = typedExpr(tree.expr, ptArg)
         val expr1 = if ctx.explicitNulls && (!ctx.mode.is(Mode.Pattern)) then
             if expr0.tpe.isNullType then
+              // If the type of the argument is `Null`, we cast it to array directly.
               expr0.cast(pt.translateParameterized(defn.RepeatedParamClass, defn.ArrayClass))
             else
+              // We need to make sure its type is no longer nullable
               expr0.castToNonNullable
           else expr0
         val fromCls = if expr1.tpe.derivesFrom(defn.ArrayClass, isErased = unsafeNullsEnabled)

docs/docs/internals/explicit-nulls.md

@@ -9,7 +9,7 @@ with union types: e.g. `val x: String | Null = null`.
 
 The implementation of the feature in dotty can be conceptually divided in several parts:
   1. changes to the type hierarchy so that `Null` is only a subtype of `Any`
-  2. a "translation layer" for Java interop that exposes the nullability in Java APIs
+  2. a "translation layer" for Java interoperability that exposes the nullability in Java APIs
   3. a `unsafeNulls` language feature which enables implicit unsafe conversion between `T` and `T | Null`
 
 ## Explicit-Nulls Flag
@@ -21,7 +21,7 @@ The explicit-nulls flag is currently disabled by default. It can be enabled via
 
 We change the type hierarchy so that `Null` is only a subtype of `Any` by:
   - modifying the notion of what is a nullable class (`isNullableClass`) in `SymDenotations`
-    to include _only_ `Null` and `Any`
+    to include _only_ `Null` and `Any`, which is used by `TypeComparer`
   - changing the parent of `Null` in `Definitions` to point to `Any` and not `AnyRef`
   - changing `isBottomType` and `isBottomClass` in `Definitions`
 
@@ -31,7 +31,7 @@ There are some utility functions for nullable types in `NullOpsDecorator.scala`.
 They are extension methods for `Type`; hence we can use them in this way: `tp.f(...)`.
 
 - `stripNullWhenExplicit` syntactically strips all `Null` types in the union:
-  e.g. `String|Null => String`.
+  e.g. `T | Null => T`. This should only be used if we can guarantee `T` is a reference type.
 - `isNullableUnion` determines whether `this` is a nullable union.
 - `isNullableAfterErasure` determines whether `this` type can have `null` value after erasure.
 
@@ -43,7 +43,7 @@ Within `Types.scala`, we also defined an extractor `OrNull` to extract the non-n
   case _ => // otherwise
 ```
 
-## Java Interop
+## Java Interoperability
 
 The problem we're trying to solve here is: if we see a Java method `String foo(String)`,
 what should that method look like to Scala?
@@ -79,6 +79,14 @@ The `matches` function in `Types.scala` is used to select condidated for overrid
 
 The `compatibleTypes` in `RefCheck.scala` determines whether the overriding types are compatible.
 
+## Nullified Upper Bound
+
+Suppose we have a type bound `class C[T >: Null <: String]`, it becomes unapplicable in explicit nulls, since
+we don't have a type that is a supertype of `Null` and a subtype of `String`.
+
+Hence, when we read a type bound from Scala 2 Tasty or Scala 3 Tasty, the upper bound is nullified if the lower
+bound is exactly `Null`. The example above would become `class C[T >: Null <: String | Null]`.
+
 ## Unsafe Nulls
 
 The `unsafeNulls` language feature is currently disabled by default. It can be enabled by importing `scala.language.unsafeNulls` or using `-language:unsafeNulls`. The feature object is defined in `library/src/scalaShadowing/language.scala`. We can use `config.Feature.enabled(nme.unsafeNulls)` to check if this feature is enabled.

docs/docs/reference/other-new-features/explicit-nulls.md

@@ -436,12 +436,16 @@ Users can import `scala.language.unsafeNulls` to create such scopes, or use `-la
 
 Assume `T` is a reference type (a subtype of `AnyRef`), the following unsafe operation rules are
 applied in this unsafe-nulls scope:
+
 1. the members of `T` can be found on `T | Null`
+
 2. a value with type `T` can be compared with `T | Null` and `Null`
+
 3. suppose `T1` is not a subtype of `T2` using explicit-nulls subtyping (where `Null` is a direct
 subtype of Any), extension methods and implicit conversions designed for `T2` can be used for
 `T1` if `T1` is a subtype of `T2` using regular subtyping rules (where `Null` is a subtype of every
 reference type)
+
 4. suppose `T1` is not a subtype of `T2` using explicit-nulls subtyping, a value with type `T1`
 can be used as `T2` if `T1` is a subtype of `T2` using regular subtyping rules