Provide more documentation on functions and types

CHANGELOG.md

@@ -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.

README.md

@@ -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
+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
 

src/Language/GraphQL/AST/Core.hs

@@ -19,30 +19,84 @@ 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.
-               | Mutation (Maybe Text) (NonEmpty Field)
+--
-                 deriving (Eq,Show)
+-- Currently only queries and mutations are supported.
+data Operation
+    = Query (Maybe Text) (NonEmpty Field)
+    | Mutation (Maybe Text) (NonEmpty Field)
+    deriving (Eq, Show)
 
-data Field = Field (Maybe Alias) Name [Argument] [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
 
-data Argument = Argument Name Value deriving (Eq,Show)
+-- | 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.
-           -- GraphQL Float is double precision
+data Value
-           | ValueFloat Double
+    = ValueInt Int32
-           | ValueString Text
+    -- GraphQL Float is double precision
-           | ValueBoolean Bool
+    | ValueFloat Double
-           | ValueNull
+    | ValueString Text
-           | ValueEnum Name
+    | ValueBoolean Bool
-           | ValueList [Value]
+    | ValueNull
-           | ValueObject [ObjectField]
+    | ValueEnum Name
-             deriving (Eq,Show)
+    | ValueList [Value]
+    | ValueObject [ObjectField]
+    deriving (Eq, Show)
 
 instance IsString Value where
   fromString = ValueString . fromString
 
-data ObjectField = ObjectField Name Value deriving (Eq,Show)
+-- | Key-value pair.
+--
+-- A list of 'ObjectField's represents a GraphQL object type.
+data ObjectField = ObjectField Name Value deriving (Eq, Show)

src/Language/GraphQL/Lexer.hs

@@ -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
 

src/Language/GraphQL/Parser.hs

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

src/Language/GraphQL/Trans.hs

@@ -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

stack.yaml

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