Merge branch 'all-improvements'

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

Data/GraphQL/Execute.hs

@@ -1,4 +1,6 @@
 {-# LANGUAGE CPP #-}
+-- | This module provides the function to execute a @GraphQL@ request --
+--   according to a 'Schema'.
 module Data.GraphQL.Execute (execute) where
 
 #if !MIN_VERSION_base(4,8,0)
@@ -13,16 +15,32 @@ import Data.GraphQL.AST
 import Data.GraphQL.Schema (Schema(..))
 import qualified Data.GraphQL.Schema as Schema
 
-execute
-  :: Alternative f
-  => Schema.Schema f -> Schema.Subs -> Document -> f Aeson.Value
-execute (Schema resolvs) subs = Schema.resolvers resolvs . rootFields subs
+import Data.GraphQL.Error
 
+-- | Takes a 'Schema', a variable substitution function ('Schema.Subs'), and a
+--   @GraphQL@ 'document'. The substitution is applied to the document using
+--  'rootFields', and the 'Schema''s resolvers are applied to the resulting fields.
+--
+--   Returns the result of the query against the 'Schema' wrapped in a /data/ field, or
+--   errors wrapped in an /errors/ field.
+execute :: Alternative f
+  => Schema.Schema f -> Schema.Subs -> Document -> f Aeson.Value
+execute (Schema resolvs) subs doc = runCollectErrs res
+  where res = Schema.resolvers resolvs $ rootFields subs doc
+
+-- | Takes a variable substitution function and a @GraphQL@ document.
+--   If the document contains one query (and no other definitions)
+--   it applies the substitution to the query's set of selections
+--   and then returns their fields.
 rootFields :: Schema.Subs -> Document -> [Field]
 rootFields subs (Document [DefinitionOperation (Query (Node _varDefs _ _ sels))]) =
     Schema.fields $ substitute subs <$> sels
 rootFields _ _ = []
 
+-- | Takes a variable substitution function and a selection. If the
+--   selection is a field it applies the substitution to the field's
+--   arguments using 'subsArg', and recursively applies the substitution to
+--   the arguments of fields nested in the primary field.
 substitute :: Schema.Subs -> Selection -> Selection
 substitute subs (SelectionField (Field alias name args directives sels)) =
     SelectionField $ Field
@@ -35,6 +53,9 @@ substitute subs (SelectionField (Field alias name args directives sels)) =
 substitute _ sel = sel
 
 -- TODO: Support different value types
+-- | Takes a variable substitution function and an argument. If the
+--   argument's value is a variable the substitution is applied to the
+--   variable's name.
 subsArg :: Schema.Subs -> Argument -> Maybe Argument
 subsArg subs (Argument n (ValueVariable (Variable v))) =
     Argument n . ValueString <$> subs v