Merge branch 'all-improvements'

This adds general API documentation, a tutorial and error handling.

Data/GraphQL/AST.hs

@@ -1,3 +1,6 @@
+-- | This module defines an abstract syntax tree for the @GraphQL@ language based on
+--   <https://facebook.github.io/graphql/ Facebook's GraphQL Specification>.
+
 module Data.GraphQL.AST where
 
 import Data.Int (Int32)
@@ -39,11 +42,26 @@ data Selection = SelectionField Field
                | SelectionInlineFragment InlineFragment
                  deriving (Eq,Show)
 
+-- | A 'SelectionSet' is primarily composed of 'Field's. A 'Field' describes one
+--   discrete piece of information available to request within a 'SelectionSet'.
+--
+--   Some 'Field's describe complex data or relationships to other data. In
+--   order to further explore this data, a 'Field' may itself contain a
+--   'SelectionSet', allowing for deeply nested requests. All @GraphQL@ operations
+--   must specify their 'Selection's down to 'Field's which return scalar values to
+--   ensure an unambiguously shaped response.
+--
+--   <https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields Field Specification>
 data Field = Field Alias Name [Argument] [Directive] SelectionSet
              deriving (Eq,Show)
 
 type Alias = Name
 
+-- | 'Field's are conceptually functions which return values, and occasionally accept
+--   'Argument's which alter their behavior. These 'Argument's often map directly to
+--   function arguments within a @GraphQL@ server’s implementation.
+--
+--   <https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments Argument Specification>
 data Argument = Argument Name Value deriving (Eq,Show)
 
 -- * Fragments
@@ -63,6 +81,15 @@ type TypeCondition = NamedType
 
 -- * Values
 
+-- | 'Field' and 'Directive' 'Arguments' accept input values of various literal
+--   primitives; input values can be scalars, enumeration values, lists, or input
+--   objects.
+--
+--   If not defined as constant (for example, in 'DefaultValue'), input values
+--   can be specified as a 'Variable'. List and inputs objects may also contain
+--   'Variable's (unless defined to be constant).
+--
+--   <https://facebook.github.io/graphql/#sec-Input-Values Input Value Specification>
 data Value = ValueVariable Variable
            | ValueInt Int32
            -- GraphQL Float is double precison