rewrote generic classes tour

Author: travissarles

tutorials/tour/_posts/2017-02-13-generic-classes.md

@@ -9,40 +9,50 @@ categories: tour
 num: 18
 next-page: variances
 previous-page: sequence-comprehensions
+assumed-knowledge: classes unified-types
 ---
+Generic classes are classes which take a type as a parameter. They are particularly useful for collection classes.
 
-Like in Java 5 (aka. [JDK 1.5](http://java.sun.com/j2se/1.5/)), Scala has built-in support for classes parameterized with types. Such generic classes are particularly useful for the development of collection classes.
-Here is an example which demonstrates this:
-
+## Defining a generic class
+Generic classes take a type as a parameter within square brackets `[]`. One convention is to use the letter `T` as type parameter identifier, though this is not required.
 ```tut
 class Stack[T] {
-  var elems: List[T] = Nil
-  def push(x: T) { elems = x :: elems }
-  def top: T = elems.head
-  def pop() { elems = elems.tail }
+  private var elements: List[T] = Nil
+  def push(x: T) { elements = x :: elements }
+  def peek: T = elements.head
+  def pop(): T = {
+    val currentTop = peek
+    elements = elements.tail
+    currentTop
+  }
 }
 ```
+This implementation of a `Stack` class takes any type `T` as a parameter. This means the underlying list, `var elements: List[T] = Nil`, can only store elements of type `T`. The procedure `def push` only accepts objects of type `T` (note: `elements = x :: elements` reassigns `elements` to a new list created by prepending `x` to the current `elements`).
 
-Class `Stack` models imperative (mutable) stacks of an arbitrary element type `T`. The type parameters enforces that only legal elements (that are of type `T`) are pushed onto the stack. Similarly, with type parameters we can express that method `top` will only yield elements of the given type.
+## Usage
 
-Here are some usage examples:
+To use a generic class, put the type in the square brackets in place of `T`.
+```
+val stack = new Stack[Int]
+stack.push(1)
+stack.push(2)
+println(stack.pop)  // prints 2
+println(stack.pop)  // prints 1
+```
 
-```tut
-object GenericsTest extends App {
-  val stack = new Stack[Int]
-  stack.push(1)
-  stack.push('a')
-  println(stack.top)
-  stack.pop()
-  println(stack.top)
-}
+This Stack class can accept subtypes of the type argument:
 ```
+class Fruit
+class Apple extends Fruit
+class Banana extends Fruit
 
-The output of this program will be:
+val stack = new Stack[Fruit]
+val apple = new Apple
+val banana = new Banana
 
+stack.push(apple)
+stack.push(banana)
 ```
-97
-1
-```
+Class `Apple` and `Banana` both extend `Fruit` so we can push instances `apple` and `banana` onto the stack of `Fruit`.
 
 _Note: subtyping of generic types is *invariant*. This means that if we have a stack of characters of type `Stack[Char]` then it cannot be used as an integer stack of type `Stack[Int]`. This would be unsound because it would enable us to enter true integers into the character stack. To conclude, `Stack[T]` is only a subtype of `Stack[S]` if and only if `S = T`. Since this can be quite restrictive, Scala offers a [type parameter annotation mechanism](variances.html) to control the subtyping behavior of generic types._