Clarify documentation

Author: Blaisorblade

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

@@ -68,7 +68,9 @@ class CheckRealizable(implicit ctx: Context) {
    */
   private def isLateInitialized(sym: Symbol) = sym.is(Lazy, butNot = Module)
 
-  /** The realizability status of given type `tp` */
+  /** The realizability status of given type `tp`. We can only select members from realizable types.
+    * A type is realizable if it has non-null values. However, realizable types can
+    * have non-realizable subtypes, so we must restrict overriding. */
   def realizability(tp: Type): Realizability = tp.dealias match {
     case tp: TermRef =>
       // Suppose tp is a.b.c.type, where c is declared with type T, then sym is c, tp.info is T and
@@ -83,6 +85,7 @@ class CheckRealizable(implicit ctx: Context) {
         def patchRealizability(r: Realizability) =
           r.mapError(if (tp.info.isStableRealizable) Realizable else _)
         val r =
+          // Reject fields that are mutable, by-name, and similar.
           if (!sym.isStable)
             patchRealizability(NotStable)
             // 3. If the symbol isn't "lazy" and its prefix is realizable
@@ -91,10 +94,13 @@ class CheckRealizable(implicit ctx: Context) {
             // stable if it appears under a realizable prefix.
             // XXX: Add object DependsOnPrefix extends Realizability(""), but filter it out here.
             patchRealizability(realizability(tp.prefix))
-            // 4. If the symbol can't be overridden, and
           else if (!sym.isEffectivelyFinal)
             patchRealizability(new NotFinal(sym))
           else
+            // 4. If the symbol is effectively final, and a lazy or erased val
+            // and has a realizable type. We require finality because overrides
+            // of realizable fields might not be realizable.
+
             // Since patchRealizability checks realizability(tp.info) through
             // isStableRealizable, using patchRealizability wouldn't make
             // a difference, and calling it here again might introduce