Merge pull request #14883 from dotty-staging/fix-12689

Add class diagrams with Matchable

Author: odersky

docs/_assets/images/explicit-nulls/explicit-nulls-type-hierarchy.png

@@ -31,12 +31,17 @@ Read on for details.
 
 ## New Type Hierarchy
 
-When explicit nulls are enabled, the type hierarchy changes so that `Null` is only a subtype of
-`Any`, as opposed to every reference type, which means `null` is no longer a value of `AnyRef` and its subtypes.
+Originally, `Null` is a subtype of all reference types.
+
+!["Original Type Hierarchy"](images/explicit-nulls/scalaHierarchyWithMatchable.png)
+
+When explicit nulls is enabled, the type hierarchy changes so that `Null` is only
+a subtype of `Any` and `Matchable`, as opposed to every reference type,
+which means `null` is no longer a value of `AnyRef` and its subtypes.
 
 This is the new type hierarchy:
 
-!["Type Hierarchy for Explicit Nulls"](images/explicit-nulls/explicit-nulls-type-hierarchy.png)
+!["Type Hierarchy for Explicit Nulls"](images/explicit-nulls/scalaHierarchyWithMatchableAndSafeNull.png)
 
 After erasure, `Null` remains a subtype of all reference types (as forced by the JVM).