Clarify: Combining List and Non-Null (#440)

As pointed out in #228 this clarifying point should not be contained in the introspection system. Instead this makes more sense in the context of the type system definitions.

Also expands to include coercion examples mirroring the list examples above.

Closes #228

Author: leebyron

spec/Section 3 -- Type System.md

@@ -1517,6 +1517,39 @@ a non-null input type as invalid.
 1. A Non-Null type must not wrap another Non-Null type.
 
 
+### Combining List and Non-Null
+
+The List and Non-Null wrapping types can compose, representing more complex
+types. The rules for result coercion and input coercion of Lists and Non-Null
+types apply in a recursive fashion.
+
+For example if the inner item type of a List is Non-Null (e.g. `[T!]`), then
+that List may not contain any {null} items. However if the inner type of a
+Non-Null is a List (e.g. `[T]!`), then {null} is not accepted however an empty
+list is accepted.
+
+Following are examples of result coercion with various types and values:
+
+Expected Type | Internal Value   | Coerced Result
+------------- | ---------------- | ---------------------------
+`[Int]`       | `[1, 2, 3]`      | `[1, 2, 3]`
+`[Int]`       | `null`           | `null`
+`[Int]`       | `[1, 2, null]`   | `[1, 2, null]`
+`[Int]`       | `[1, 2, Error]`  | `[1, 2, null]` (With logged error)
+`[Int]!`      | `[1, 2, 3]`      | `[1, 2, 3]`
+`[Int]!`      | `null`           | Error: Value cannot be null
+`[Int]!`      | `[1, 2, null]`   | `[1, 2, null]`
+`[Int]!`      | `[1, 2, Error]`  | `[1, 2, null]` (With logged error)
+`[Int!]`      | `[1, 2, 3]`      | `[1, 2, 3]`
+`[Int!]`      | `null`           | `null`
+`[Int!]`      | `[1, 2, null]`   | `null` (With logged coercion error)
+`[Int!]`      | `[1, 2, Error]`  | `null` (With logged error)
+`[Int!]!`     | `[1, 2, 3]`      | `[1, 2, 3]`
+`[Int!]!`     | `null`           | Error: Value cannot be null
+`[Int!]!`     | `[1, 2, null]`   | Error: Item cannot be null
+`[Int!]!`     | `[1, 2, Error]`  | Error: Error occurred in item
+
+
 ## Directives
 
 DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? on DirectiveLocations

spec/Section 4 -- Introspection.md

@@ -361,22 +361,6 @@ required inputs for arguments and input object fields.
 * All other fields must return {null}.
 
 
-#### Combining List and Non-Null
-
-List and Non-Null can compose, representing more complex types.
-
-If the modified type of a List is Non-Null, then that List may not contain any
-{null} items.
-
-If the modified type of a Non-Null is List, then {null} is not accepted,
-however an empty list is accepted.
-
-If the modified type of a List is a List, then each item in the first List is
-another List of the second List's type.
-
-A Non-Null type cannot modify another Non-Null type.
-
-
 ### The __Field Type
 
 The `__Field` type represents each field in an Object or Interface type.