Provide more documentation on functions and types

This commit is contained in:
Eugen Wissner 2019-08-26 10:14:46 +02:00
parent f54e9451d2
commit 5175586def
7 changed files with 81 additions and 19 deletions

View File

@ -1,6 +1,10 @@
# Change Log # Change Log
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
## [Unreleased]
### Added
- Minimal documentation for all public symbols.
## [0.5.0.0] - 2019-08-14 ## [0.5.0.0] - 2019-08-14
### Added ### Added
- `executeWithName` executes an operation with the given name. - `executeWithName` executes an operation with the given name.

View File

@ -8,8 +8,8 @@ GraphQL implementation in Haskell.
This implementation is relatively low-level by design, it doesn't provide any This implementation is relatively low-level by design, it doesn't provide any
mappings between the GraphQL types and Haskell's type system and avoids mappings between the GraphQL types and Haskell's type system and avoids
compile-time magic. It focuses on flexibility instead instead, so other compile-time magic. It focuses on flexibility instead, so other solutions can
solutions can be built on top of it. be built on top of it.
## State of the work ## State of the work

View File

@ -19,19 +19,70 @@ import Data.Text (Text)
-- | Name -- | Name
type Name = Text type Name = Text
-- | GraphQL document is a non-empty list of operations.
type Document = NonEmpty Operation type Document = NonEmpty Operation
data Operation = Query (Maybe Text) (NonEmpty Field) -- | GraphQL has 3 operation types: queries, mutations and subscribtions.
--
-- Currently only queries and mutations are supported.
data Operation
= Query (Maybe Text) (NonEmpty Field)
| Mutation (Maybe Text) (NonEmpty Field) | Mutation (Maybe Text) (NonEmpty Field)
deriving (Eq, Show) deriving (Eq, Show)
-- | A single GraphQL field.
--
-- Only required property of a field, is its name. Optionally it can also have
-- an alias, arguments or a list of subfields.
--
-- Given the following query:
--
-- @
-- {
-- zuck: user(id: 4) {
-- id
-- name
-- }
-- }
-- @
--
-- * "user", "id" and "name" are field names.
-- * "user" has two subfields, "id" and "name".
-- * "zuck" is an alias for "user". "id" and "name" have no aliases.
-- * "id: 4" is an argument for "name". "id" and "name don't have any
-- arguments.
data Field = Field (Maybe Alias) Name [Argument] [Field] deriving (Eq, Show) data Field = Field (Maybe Alias) Name [Argument] [Field] deriving (Eq, Show)
-- | Alternative field name.
--
-- @
-- {
-- smallPic: profilePic(size: 64)
-- bigPic: profilePic(size: 1024)
-- }
-- @
--
-- Here "smallPic" and "bigPic" are aliases for the same field, "profilePic",
-- used to distinquish between profile pictures with different arguments
-- (sizes).
type Alias = Name type Alias = Name
-- | Single argument.
--
-- @
-- {
-- user(id: 4) {
-- name
-- }
-- }
-- @
--
-- Here "id" is an argument for the field "user" and its value is 4.
data Argument = Argument Name Value deriving (Eq, Show) data Argument = Argument Name Value deriving (Eq, Show)
data Value = ValueInt Int32 -- | Represents accordingly typed GraphQL values.
data Value
= ValueInt Int32
-- GraphQL Float is double precision -- GraphQL Float is double precision
| ValueFloat Double | ValueFloat Double
| ValueString Text | ValueString Text
@ -45,4 +96,7 @@ data Value = ValueInt Int32
instance IsString Value where instance IsString Value where
fromString = ValueString . fromString fromString = ValueString . fromString
-- | Key-value pair.
--
-- A list of 'ObjectField's represents a GraphQL object type.
data ObjectField = ObjectField Name Value deriving (Eq, Show) data ObjectField = ObjectField Name Value deriving (Eq, Show)

View File

@ -71,6 +71,8 @@ type Parser = Parsec Void T.Text
ignoredCharacters :: Parser () ignoredCharacters :: Parser ()
ignoredCharacters = space1 <|> skipSome (char ',') ignoredCharacters = space1 <|> skipSome (char ',')
-- | Parser that skips comments and meaningless characters, whitespaces and
-- commas.
spaceConsumer :: Parser () spaceConsumer :: Parser ()
spaceConsumer = Lexer.space ignoredCharacters comment empty spaceConsumer = Lexer.space ignoredCharacters comment empty

View File

@ -16,6 +16,7 @@ import Text.Megaparsec ( lookAhead
, (<?>) , (<?>)
) )
-- | Parser for the GraphQL documents.
document :: Parser Document document :: Parser Document
document = unicodeBOM >> spaceConsumer >> lexeme (manyNE definition) document = unicodeBOM >> spaceConsumer >> lexeme (manyNE definition)

View File

@ -9,6 +9,7 @@ import Control.Monad.Trans.Class (MonadTrans(..))
import Control.Monad.Trans.Except (ExceptT) import Control.Monad.Trans.Except (ExceptT)
import Data.Text (Text) import Data.Text (Text)
-- | Monad transformer stack used by the resolvers to provide error handling.
newtype ActionT m a = ActionT { runActionT :: ExceptT Text m a } newtype ActionT m a = ActionT { runActionT :: ExceptT Text m a }
instance Functor m => Functor (ActionT m) where instance Functor m => Functor (ActionT m) where

View File

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