[Work in progress] Improve ast doc + adding contributions "guidelines"

CONTRIBUTE.md

@@ -0,0 +1,18 @@
+## Setup
+
+This project use [stack](https://docs.haskellstack.org/en/stable/README/.
+Dowload the project from github and run:
+```
+stack --stack-yaml=stack-8.?.yaml build
+```
+You can also build the doc with 
+```
+stack haddock
+````
+
+## faq
+
+Why is there a makefile ? 
+why is there no default stack.yml ? (required for some ide tools)
+
+-> current master branch contains code for the **next release**, current release is on hackage and its source code is available in a branch

README.md

@@ -38,6 +38,7 @@ We can define this schema in Haskell and implement a simple handler like so:
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TypeApplications #-}
 {-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE DataKinds #-}
 
 import Data.Text (Text)
 import Data.Monoid ((<>))

graphql-api.cabal

@@ -1,8 +1,8 @@
--- This file has been generated from package.yaml by hpack version 0.20.0.
+-- This file has been generated from package.yaml by hpack version 0.28.2.
 --
 -- see: https://github.com/sol/hpack
 --
--- hash: 6a38b887cec0d4a157469f5d73041fd16cb286d8f445f4e213c6f08965dbc563
+-- hash: 6db006b020fe198ac64b8a50f8335017251389b7c34dfc553675e38eb001a428
 
 name:           graphql-api
 version:        0.3.0
@@ -23,7 +23,6 @@ license:        Apache
 license-file:   LICENSE.Apache-2.0
 build-type:     Simple
 cabal-version:  >= 1.10
-
 extra-source-files:
     CHANGELOG.rst
 

src/GraphQL/Internal/Syntax/AST.hs

@@ -77,9 +77,26 @@ data OperationDefinition
   | AnonymousQuery SelectionSet
   deriving (Eq,Show)
 
+-- | A node is the opening of a 'SelectionSet' (materialized by curly braces) in an 'OperationDefinition' 
+--
+-- Example :
+-- @
+-- query Test { drinkList {id name} }
+-- @
+-- Contains 2 nodes: drinkList and Test
+-- 
 data Node = Node (Maybe Name) [VariableDefinition] [Directive] SelectionSet
             deriving (Eq,Show)
 
+
+-- | A variable defined within in the context of a 'QueryDocument' 
+-- 
+-- Example :
+-- @
+-- query RollDice($dice: Int!, $sides: Int) { rollDice(numDice: $dice, numSides: $sides) }
+-- @
+-- Contains 2 'VariableDefinition' : @$dice: Int! = 3@ and @$sides: Int@ are
+--
 data VariableDefinition = VariableDefinition Variable GType (Maybe DefaultValue)
                           deriving (Eq,Show)
 
@@ -100,6 +117,14 @@ data Field = Field (Maybe Alias) Name [Argument] [Directive] SelectionSet
 
 type Alias = Name
 
+-- | An argument is a value passed to a 'Field', 'Directive' etc
+-- see also 'GraphQL.Internal.Validation.Arguments'
+-- Example :
+-- @
+-- query RollDice($dice: Int!, $sides: Int) { rollDice(numDice: $dice, numSides: $sides) }
+-- @
+-- numDice is an argument passed to the Field rollDice
+--
 data Argument = Argument Name Value deriving (Eq,Show)
 
 -- * Fragments
@@ -143,6 +168,7 @@ instance Arbitrary Value where
                     , pure ValueNull
                     ]
 
+-- | Simple alias for Text to decode a string value              
 newtype StringValue = StringValue Text deriving (Eq,Show)
 
 instance Arbitrary StringValue where
@@ -186,6 +212,7 @@ data NonNullType = NonNullTypeNamed NamedType
 
 -- * Type definition
 
+-- | A TypeDefinition is a GraphQL type defined in a user's Schema
 data TypeDefinition = TypeDefinitionObject        ObjectTypeDefinition
                     | TypeDefinitionInterface     InterfaceTypeDefinition
                     | TypeDefinitionUnion         UnionTypeDefinition
@@ -194,7 +221,7 @@ data TypeDefinition = TypeDefinitionObject        ObjectTypeDefinition
                     | TypeDefinitionInputObject   InputObjectTypeDefinition
                     | TypeDefinitionTypeExtension TypeExtensionDefinition
                       deriving (Eq,Show)
-
+          
 data ObjectTypeDefinition = ObjectTypeDefinition Name Interfaces [FieldDefinition]
                             deriving (Eq,Show)
 

stack.yaml

@@ -0,0 +1,7 @@
+# LTS 10.4 is the latest LTS that supports GHC 8.2 at the time of writing.
+resolver: lts-10.4
+
+packages:
+  - "."
+  - "./docs/source/tutorial"
+  - "./graphql-wai"