Update doc, WIP

Author: noti0na1

docs/docs/internals/explicit-nulls.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: "Explicit Nulls"
 ---
 
-The "explicit nulls" feature (enabled via a flag) changes the Scala type hierarchy
+The explicit nulls feature (enabled via a flag) changes the Scala type hierarchy
 so that reference types (e.g. `String`) are non-nullable. We can still express nullability
 with union types: e.g. `val x: String|Null = null`.
 
@@ -13,21 +13,21 @@ The implementation of the feature in dotty can be conceptually divided in severa
   3. a "magic" `JavaNull` type (an alias for `Null`) that is recognized by the compiler and
      allows unsound member selections (trading soundness for usability)
 
-Feature Flag
-------------
+## Feature Flag
+
 Explicit nulls are disabled by default. They can be enabled via `-Yexplicit-nulls` defined in
 `ScalaSettings.scala`. All of the explicit-nulls-related changes should be gated behind the flag.
 
-Type Hierarchy
---------------
+## Type Hierarchy
+
 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`
   - changing the parent of `Null` in `Definitions` to point to `Any` and not `AnyRef`
   - changing `isBottomType` and `isBottomClass` in `Definitions`
 
-Java Interop
-------------
+## Java Interop
+
 TODO(abeln): add support for recognizing nullability annotations a la
 https://kotlinlang.org/docs/reference/java-interop.html#nullability-annotations
 
@@ -63,8 +63,8 @@ function `n`:
   8. n((A1, ..., Am)R) = (n(A1), ..., n(Am))n(R) for a method with arguments (A1, ..., Am) and return type R
   9. n(T)              = T                       otherwise
 
-JavaNull
---------
+## JavaNull
+
 `JavaNull` is just an alias for `Null`, but with magic power. `JavaNull`'s magic (anti-)power is that
 it's unsound.
 
@@ -79,8 +79,8 @@ The logic to allow member selections is defined in `findMember` in `Types.scala`
   - and the union contains `JavaNull` on the r.h.s. after normalization (see below)
   - then we can continue with `findMember` on the l.h.s of the union (as opposed to failing)
 
-Working with Nullable Unions
-----------------------------
+## Working with Nullable Unions
+
 Within `Types.scala`, we defined a few utility methods to work with nullable unions. All of these
 are methods of the `Type` class, so call them with `this` as a receiver:
   - `isNullableUnion` determines whether `this` is a nullable union. Here, what constitutes
@@ -98,3 +98,7 @@ are methods of the `Type` class, so call them with `this` as a receiver:
      we'll get `Array[String|Null]` (only the outermost nullable union was removed).
   - `stripAllJavaNull` is like `stripNull` but removes _all_ nullable unions in the type (and only works
      for `JavaNull`). This is needed when we want to "revert" the Java nullification function.
+
+## Flow Typing
+
+TODO