Lower bound in tour includes dangers

_tour/lower-type-bounds.md

@@ -16,52 +16,56 @@ While [upper type bounds](upper-type-bounds.html) limit a type to a subtype of a
 Here is an example where this is useful:
 
 ```scala mdoc:fail
-trait Node[+B] {
-  def prepend(elem: B): Node[B]
+trait List[+B] {
+  def prepend(elem: B): NonEmptyList[B] = NonEmptyList(elem, this)
 }
 
-case class ListNode[+B](h: B, t: Node[B]) extends Node[B] {
-  def prepend(elem: B): ListNode[B] = ListNode(elem, this)
-  def head: B = h
-  def tail: Node[B] = t
-}
+case class NonEmptyList[+B](head: B, tail: List[B]) extends List[B]
 
-case class Nil[+B]() extends Node[B] {
-  def prepend(elem: B): ListNode[B] = ListNode(elem, this)
-}
+object Nil extends List[Nothing]
 ```
 
-This program implements a singly-linked list. `Nil` represents an empty element (i.e. an empty list). `class ListNode` is a node which contains an element of type `B` (`head`) and a reference to the rest of the list (`tail`). The `class Node` and its subtypes are covariant because we have `+B`.
+This program implements a singly-linked list. `Nil` represents an empty list with no elements. `class NonEmptyList` is a node which contains an element of type `B` (`head`) and a reference to the rest of the list (`tail`). The `trait List` and its subtypes are covariant because we have `+B`.
 
 However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `B`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types.
 
 To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `U` that has `B` as a lower type bound.
 
 ```scala mdoc
-trait Node[+B] {
-  def prepend[U >: B](elem: U): Node[U]
+trait List[+B] {
+  def prepend[U >: B](elem: U): NonEmptyList[U] = NonEmptyList(elem, this)
 }
 
-case class ListNode[+B](h: B, t: Node[B]) extends Node[B] {
-  def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this)
-  def head: B = h
-  def tail: Node[B] = t
-}
+case class NonEmptyList[+B](head: B, tail: List[B]) extends List[B]
 
-case class Nil[+B]() extends Node[B] {
-  def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this)
-}
+object Nil extends List[Nothing]
 ```
 
+The type parameter for `List` is `B` to suggest we want to keep lists of birds.
+
 Now we can do the following:
 ```scala mdoc
 trait Bird
 case class AfricanSwallow() extends Bird
 case class EuropeanSwallow() extends Bird
 
+val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow())
+val swallowsFromAntarctica: List[Bird] = Nil
 
-val africanSwallowList = ListNode[AfricanSwallow](AfricanSwallow(), Nil())
-val birdList: Node[Bird] = africanSwallowList
-birdList.prepend(EuropeanSwallow())
+// assign swallows to birds
+val birds: List[Bird] = africanSwallows
+
+// add a swallow to birds
+val moreBirds = birds.prepend(EuropeanSwallow())
+
+// add disparate swallows together to get birds
+val allBirds = africanSwallows.prepend(EuropeanSwallow())
+
+// but this is a mistake! adding a list of birds widens the type arg too much. -Xlint will warn!
+val error = moreBirds.prepend(swallowsFromAntarctica)
 ```
-The `Node[Bird]` can be assigned the `africanSwallowList` but then accept `EuropeanSwallow`s.
+The covariant type parameter allows `birds` to get the value of `africanSwallows`.
+
+The type bound on the type parameter for `prepend` allows adding different varieties of swallows and getting a wider type: instead of `List[AfricanSwallow]`, we get a `List[Bird]`.
+
+The canary in the coal mine is `-Xlint`, which will warn if the type arg is widened too much.