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
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
### Added
- `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
mappings between the GraphQL types and Haskell's type system and avoids
compile-time magic. It focuses on flexibility instead instead, so other
solutions can be built on top of it.
compile-time magic. It focuses on flexibility instead, so other solutions can
be built on top of it.
## State of the work

View File

@ -19,19 +19,70 @@ import Data.Text (Text)
-- | Name
type Name = Text
-- | GraphQL document is a non-empty list of operations.
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)
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)
-- | 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
-- | 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 Value = ValueInt Int32
-- | Represents accordingly typed GraphQL values.
data Value
= ValueInt Int32
-- GraphQL Float is double precision
| ValueFloat Double
| ValueString Text
@ -45,4 +96,7 @@ data Value = ValueInt Int32
instance IsString Value where
fromString = ValueString . fromString
-- | Key-value pair.
--
-- A list of 'ObjectField's represents a GraphQL object type.
data ObjectField = ObjectField Name Value deriving (Eq, Show)

View File

@ -71,6 +71,8 @@ type Parser = Parsec Void T.Text
ignoredCharacters :: Parser ()
ignoredCharacters = space1 <|> skipSome (char ',')
-- | Parser that skips comments and meaningless characters, whitespaces and
-- commas.
spaceConsumer :: Parser ()
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 = unicodeBOM >> spaceConsumer >> lexeme (manyNE definition)

View File

@ -9,6 +9,7 @@ import Control.Monad.Trans.Class (MonadTrans(..))
import Control.Monad.Trans.Except (ExceptT)
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 }
instance Functor m => Functor (ActionT m) where

View File

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