Add comments

Author: noti0na1

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

@@ -911,6 +911,8 @@ trait Applications extends Compatibility {
           case funRef: TermRef =>
             var app = ApplyTo(tree, fun1, funRef, proto, pt)
             if ctx.mode.is(Mode.UnsafeJavaReturn) then
+              // When UnsafeJavaReturn is enabled and the applied function is Java defined,
+              // we replece `| Null` with `@CanEqualNull` in the return type.
               val funSym = fun1.symbol
               if funSym.is(JavaDefined)
                 && funSym.isTerm

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

@@ -159,15 +159,17 @@ class Synthesizer(typer: Typer)(using @constructorOnly c: Context):
         cmpWithBoxed(cls2, cls1)
       else if ctx.mode.is(Mode.SafeNulls) then
         // If explicit nulls is enabled, and unsafeNulls is not enabled,
+        // and the types don't have `@CanEqualNull` annotation,
         // we want to disallow comparison between Object and Null.
         // If we have to check whether a variable with a non-nullable type has null value
         // (for example, a NotNull java method returns null for some reasons),
-        // we can still cast it to a nullable type then compare its value.
+        // we can still use `eq/ne null` or cast it to a nullable type then compare its value.
         //
         // Example:
         // val x: String = null.asInstanceOf[String]
         // if (x == null) {} // error: x is non-nullable
         // if (x.asInstanceOf[String|Null] == null) {} // ok
+        // if (x eq null) {} // ok
         cls1 == defn.NullClass && cls1 == cls2
       else if cls1 == defn.NullClass then
         cls1 == cls2 || cls2.derivesFrom(defn.ObjectClass)
@@ -182,6 +184,14 @@ class Synthesizer(typer: Typer)(using @constructorOnly c: Context):
       *  interpret.
       */
     def canComparePredefined(tp1: Type, tp2: Type) =
+      // In explicit nulls, when one of type has `@CanEqualNull` annotation,
+      // we use unsafe nulls semantic to check, which allows reference types
+      // to be compared with `Null`.
+      // Example:
+      // val s1: String = ???
+      // s1 == null // error
+      // val s2: String @CanEqualNull = ???
+      // s2 == null // ok
       val checkCtx = if ctx.explicitNulls
         && (tp1.hasAnnotation(defn.CanEqualNullAnnot) || tp2.hasAnnotation(defn.CanEqualNullAnnot))
         then ctx.retractMode(Mode.SafeNulls) else ctx

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

@@ -657,6 +657,9 @@ class Typer(@constructorOnly nestingLevel: Int = 0) extends Namer
       else qual
       var sel = typedSelect(tree, pt, qual1).withSpan(tree.span).computeNullable()
       if ctx.mode.is(Mode.UnsafeJavaReturn) && pt != AssignProto then
+        // When UnsafeJavaReturn is enabled and the selected member is Java defined,
+        // we replece `| Null` with `@CanEqualNull` in its type
+        // if it is not at left hand side of assignments.
         val sym = sel.symbol
         if sym.is(JavaDefined) && sym.isTerm && !sym.is(Method) then
           val stp1 = sel.tpe.widen

compiler/test/dotty/tools/dotc/CompilationTests.scala

@@ -250,6 +250,7 @@ class CompilationTests {
       compileFilesInDir("tests/explicit-nulls/pos-separate", explicitNullsOptions),
       compileFilesInDir("tests/explicit-nulls/pos-patmat", explicitNullsOptions and "-Xfatal-warnings"),
       compileFilesInDir("tests/explicit-nulls/unsafe-common", explicitNullsOptions and "-language:unsafeNulls"),
+      compileFilesInDir("tests/explicit-nulls/unsafe-java", explicitNullsOptions),
       compileFile("tests/explicit-nulls/pos-special/i14682.scala", explicitNullsOptions and "-Ysafe-init"),
       compileFile("tests/explicit-nulls/pos-special/i14947.scala", explicitNullsOptions and "-Ytest-pickler" and "-Xprint-types"),
     )