Document all public symbols.

Mostly basic documentation. Fixes #4.

CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Minimal documentation for all public symbols.
 
+### Deprecated
+- Language.GraphQL.AST.FragmentName. Replaced with Language.GraphQL.AST.Name.
+
 ## [0.5.0.0] - 2019-08-14
 ### Added
 - `executeWithName` executes an operation with the given name.

semaphoreci.sh

@@ -20,6 +20,7 @@ test() {
 
 test_docs() {
 	$STACK --no-terminal ghc -- -Wall -fno-code docs/tutorial/tutorial.lhs
+        $STACK --no-terminal haddock --no-haddock-deps
 }
 
 setup_lint() {

src/Language/GraphQL/AST.hs

@@ -39,14 +39,17 @@ import Language.GraphQL.AST.Core ( Alias
 
 -- * Document
 
+-- | GraphQL document.
 type Document = NonEmpty Definition
 
 -- * Operations
 
+-- | Top-level definition of a document, either an operation or a fragment.
 data Definition = DefinitionOperation OperationDefinition
                 | DefinitionFragment  FragmentDefinition
                   deriving (Eq, Show)
 
+-- | Operation definition.
 data OperationDefinition = OperationSelectionSet SelectionSet
                          | OperationDefinition   OperationType
                                                  (Maybe Name)
@@ -55,47 +58,63 @@ data OperationDefinition = OperationSelectionSet SelectionSet
                                                  SelectionSet
                            deriving (Eq, Show)
 
+-- | GraphQL has 3 operation types: queries, mutations and subscribtions.
+--
+-- Currently only queries and mutations are supported.
 data OperationType = Query | Mutation deriving (Eq, Show)
 
--- * SelectionSet
+-- * Selections
 
+-- | "Top-level" selection, selection on a operation.
 type SelectionSet = NonEmpty Selection
 
 type SelectionSetOpt = [Selection]
 
-data Selection = SelectionField          Field
+-- | Single selection element.
+data Selection
+    = SelectionField          Field
     | SelectionFragmentSpread FragmentSpread
     | SelectionInlineFragment InlineFragment
     deriving (Eq, Show)
 
 -- * Field
 
-data Field = Field (Maybe Alias) Name Arguments Directives SelectionSetOpt
+-- | GraphQL field.
+data Field
+    = Field (Maybe Alias) Name Arguments Directives SelectionSetOpt
     deriving (Eq, Show)
 
 -- * Arguments
 
+-- | Argument list.
 type Arguments = [Argument]
 
+-- | Argument.
 data Argument = Argument Name Value deriving (Eq,Show)
 
 -- * Fragments
 
+-- | Fragment spread.
 data FragmentSpread = FragmentSpread Name Directives deriving (Eq, Show)
 
+-- | Inline fragment.
 data InlineFragment = InlineFragment (Maybe TypeCondition) Directives SelectionSet
                       deriving (Eq, Show)
 
-data FragmentDefinition =
+-- | Fragment definition.
-  FragmentDefinition FragmentName TypeCondition Directives SelectionSet
+data FragmentDefinition
+    = FragmentDefinition Name TypeCondition Directives SelectionSet
     deriving (Eq, Show)
 
+{-# DEPRECATED FragmentName "Use Name instead" #-}
 type FragmentName = Name
 
+-- | Type condition.
 type TypeCondition = Name
 
 -- * Input values
 
+-- | Input value.
 data Value = ValueVariable Name
            | ValueInt Int32
            | ValueFloat Double
@@ -107,28 +126,38 @@ data Value = ValueVariable Name
            | ValueObject [ObjectField]
            deriving (Eq, Show)
 
+-- | Key-value pair.
+--
+-- A list of 'ObjectField's represents a GraphQL object type.
 data ObjectField = ObjectField Name Value deriving (Eq, Show)
 
 -- * Variables
 
+-- | Variable definition list.
 type VariableDefinitions = [VariableDefinition]
 
+-- | Variable definition.
 data VariableDefinition = VariableDefinition Name Type (Maybe Value)
                           deriving (Eq, Show)
 
 -- * Input types
 
+-- | Type representation.
 data Type = TypeNamed   Name
           | TypeList    Type
           | TypeNonNull NonNullType
             deriving (Eq, Show)
 
+
+-- | Helper type to represent Non-Null types and lists of such types.
 data NonNullType = NonNullTypeNamed Name
                  | NonNullTypeList  Type
                    deriving (Eq, Show)
 
 -- * Directives
 
+-- | Directive list.
 type Directives = [Directive]
 
+-- | Directive.
 data Directive = Directive Name [Argument] deriving (Eq, Show)

src/Language/GraphQL/AST/Transform.hs

@@ -18,7 +18,8 @@ import qualified Language.GraphQL.Schema as Schema
 --   empty list is returned.
 type Fragmenter = Core.Name -> [Core.Field]
 
--- TODO: Replace Maybe by MonadThrow with CustomError
+-- | Rewrites the original syntax tree into an intermediate representation used
+-- for query execution.
 document :: Schema.Subs -> Full.Document -> Maybe Core.Document
 document subs doc = operations subs fr ops
   where

src/Language/GraphQL/Parser.hs

@@ -94,7 +94,7 @@ fragmentDefinition = FragmentDefinition
                  <*> opt directives
                  <*> selectionSet
 
-fragmentName :: Parser FragmentName
+fragmentName :: Parser Name
 fragmentName = but (symbol "on") *> name
 
 typeCondition :: Parser TypeCondition

stack.yaml

@@ -1,4 +1,4 @@
-resolver: lts-14.2
+resolver: lts-14.3
 packages:
 - '.'
 extra-deps: []