improving the AST doc

[theobat]

I think a good way to improve the doc would be to provide examples at each level of the AST types with graphql doc snippets such as what I naively did in #145.
Something like:

#VariableDefinition -> a variable defined in a GraphQL query/mutation context like
myQuery($myVariable: MyVariableType)
# Field -> a Field takes place in a SelectionSet such as 
myParentField { myField1 myField2 } 
#Argument -> an argument is defined in front of a GraphQL Field such as 
{ myField (myArgument: "literalString")}  or { myField (myArgument: $myVariable)}

I'm going to try to put together a PR for this.

I think it would be easier for new comers to grasp what is going on in the query parsing (which is half of the job), and helps a lot when it comes to contributing

[theobat]

It seems some type/data definitions in AST and API (e.g. here and here ), are very close.
Side by side example :

-- Schema
data ObjectTypeDefinition = ObjectTypeDefinition Name Interfaces (NonEmpty FieldDefinition)
deriving (Eq, Ord, Show)
-- AST
data ObjectTypeDefinition = ObjectTypeDefinition Name Interfaces [FieldDefinition]
deriving (Eq,Show)

Furthermore, I didn't find any occurence of the various TypeDefinition from the AST module. Besides, I don't see why anything defined in the user's schema would end up in the AST, because making the schema does not require any real "parsing" (in the sense of Text -> AST.Something)
Did I miss something or is it just old code ?

[jml]

It seems some type/data definitions in AST and API are very close.

Yes! The AST represents the syntax. AST.ObjectTypeDefinition is designed to match ObjectTypeDefinition in the spec as closely as possible.

Schema.ObjectTypeDefinition has two key differences:

1. It has no type references. Any types that it might refer to have been inlined as definitions.
2. It forbids object definitions with no fields, which are allowed in the syntax but disallowed elsewhere (I can't recall exactly where—it might just be a restriction in our implementation)

Furthermore, I didn't find any occurence [sic] of the various TypeDefinition from the AST module

The parser can work just fine without an explicit AST.ObjectTypeDefinition type. To make other parts of our code more type safe, we provide an explicit Schema.ObjectTypeDefinition type.

Besides, I don't see why anything defined in the user's schema would end up in the AST

In a sense, it's just old code.

The AST, parser, and printer were all imported from a different GraphQL project (for which we're very grateful). You can see this reflected in the license and copyright.

I'd like graphql-api be able to work with parsed schema as well as our Servant-style type-level schema—certainly much of the code is re-usable—but I don't think that's the case now.