From c1943c1979a0bfd37dae3a87d863f06938176baf Mon Sep 17 00:00:00 2001 From: Eugen Wissner Date: Thu, 29 Aug 2019 07:40:50 +0200 Subject: [PATCH] Document all public symbols. Mostly basic documentation. Fixes #4. --- CHANGELOG.md | 3 ++ semaphoreci.sh | 1 + src/Language/GraphQL/AST.hs | 67 +++++++++++++++++++-------- src/Language/GraphQL/AST/Transform.hs | 3 +- src/Language/GraphQL/Parser.hs | 2 +- stack.yaml | 2 +- 6 files changed, 56 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 060ccab..1b2a8e4 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/semaphoreci.sh b/semaphoreci.sh index f77ac75..6202a09 100755 --- a/semaphoreci.sh +++ b/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() { diff --git a/src/Language/GraphQL/AST.hs b/src/Language/GraphQL/AST.hs index 667e4d7..8f40c10 100644 --- a/src/Language/GraphQL/AST.hs +++ b/src/Language/GraphQL/AST.hs @@ -39,63 +39,82 @@ 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) + deriving (Eq, Show) +-- | Operation definition. data OperationDefinition = OperationSelectionSet SelectionSet | OperationDefinition OperationType (Maybe Name) VariableDefinitions Directives SelectionSet - deriving (Eq,Show) + deriving (Eq, Show) -data OperationType = Query | Mutation 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 - | SelectionFragmentSpread FragmentSpread - | SelectionInlineFragment InlineFragment - deriving (Eq,Show) +-- | Single selection element. +data Selection + = SelectionField Field + | SelectionFragmentSpread FragmentSpread + | SelectionInlineFragment InlineFragment + deriving (Eq, Show) -- * Field -data Field = Field (Maybe Alias) Name Arguments Directives SelectionSetOpt - deriving (Eq,Show) +-- | 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 -data FragmentSpread = FragmentSpread Name Directives deriving (Eq,Show) +-- | Fragment spread. +data FragmentSpread = FragmentSpread Name Directives deriving (Eq, Show) +-- | Inline fragment. data InlineFragment = InlineFragment (Maybe TypeCondition) Directives SelectionSet - deriving (Eq,Show) + deriving (Eq, Show) -data FragmentDefinition = - FragmentDefinition FragmentName TypeCondition Directives SelectionSet - deriving (Eq,Show) +-- | Fragment definition. +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) + deriving (Eq, Show) -- * Input types +-- | Type representation. data Type = TypeNamed Name | TypeList Type | TypeNonNull NonNullType - deriving (Eq,Show) + deriving (Eq, Show) + +-- | Helper type to represent Non-Null types and lists of such types. data NonNullType = NonNullTypeNamed Name | NonNullTypeList Type - deriving (Eq,Show) + deriving (Eq, Show) -- * Directives +-- | Directive list. type Directives = [Directive] -data Directive = Directive Name [Argument] deriving (Eq,Show) +-- | Directive. +data Directive = Directive Name [Argument] deriving (Eq, Show) diff --git a/src/Language/GraphQL/AST/Transform.hs b/src/Language/GraphQL/AST/Transform.hs index 63a2c72..99e0f3e 100644 --- a/src/Language/GraphQL/AST/Transform.hs +++ b/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 diff --git a/src/Language/GraphQL/Parser.hs b/src/Language/GraphQL/Parser.hs index 4bc17b9..17482d7 100644 --- a/src/Language/GraphQL/Parser.hs +++ b/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 diff --git a/stack.yaml b/stack.yaml index 84a066f..68eb5fc 100644 --- a/stack.yaml +++ b/stack.yaml @@ -1,4 +1,4 @@ -resolver: lts-14.2 +resolver: lts-14.3 packages: - '.' extra-deps: []