From 6348b2fb57b291b925ce27e9070eecc10d560608 Mon Sep 17 00:00:00 2001
From: Gregor Kleen <gkleen@yggdrasil.li>
Date: Sat, 23 Jan 2016 11:42:45 +0000
Subject: additional documentation

---
 server/src/Thermoprint/Server.hs     | 5 +++--
 server/src/Thermoprint/Server/API.hs | 7 ++++++-
 2 files changed, 9 insertions(+), 3 deletions(-)

(limited to 'server/src')

diff --git a/server/src/Thermoprint/Server.hs b/server/src/Thermoprint/Server.hs
index 419679c..0d96de0 100644
--- a/server/src/Thermoprint/Server.hs
+++ b/server/src/Thermoprint/Server.hs
@@ -41,7 +41,7 @@ import Thermoprint.Server.Database
 import qualified Thermoprint.Server.API as API (thermoprintServer)
 import Thermoprint.Server.API hiding (thermoprintServer)
 
-  
+-- | Compile-time configuration for 'thermoprintServer'
 data Config = Config { dyreError    :: Maybe String -- ^ Set by 'Dyre' -- sent to log as an error
                      , warpSettings :: Warp.Settings -- ^ Configure 'Warp's behaviour
                      }
@@ -56,7 +56,8 @@ thermoprintServer :: ( MonadLoggerIO m
                      , MonadIO m
                      , MonadBaseControl IO m
                      , MonadReader ConnectionPool m
-                     ) => (m :~> IO) -> Config -> IO ()
+                     ) => (m :~> IO) -- ^ 'dyre' controls the base of the monad-transformer-stack ('IO') but we let the user specify the rest of it. Therefore we require a specification of how to enter the stack.
+                     -> Config -> IO ()
 -- ^ Run the server
 thermoprintServer io = Dyre.wrapMain $ Dyre.defaultParams
   { Dyre.projectName = "thermoprint-server"
diff --git a/server/src/Thermoprint/Server/API.hs b/server/src/Thermoprint/Server/API.hs
index 9559ad1..e147ac3 100644
--- a/server/src/Thermoprint/Server/API.hs
+++ b/server/src/Thermoprint/Server/API.hs
@@ -36,12 +36,16 @@ import Database.Persist.Sql
 type ProtoHandler = ReaderT HandlerInput (LoggingT IO)
 type Handler      = EitherT ServantErr ProtoHandler
 
-data HandlerInput = HandlerInput { sqlPool :: ConnectionPool
+-- ^ Runtime configuration of our handlers
+data HandlerInput = HandlerInput { sqlPool :: ConnectionPool -- ^ How to interact with 'persistent' storage
                                  }
 
 handlerNat :: ( MonadReader ConnectionPool m
               , MonadLoggerIO m
               ) => m (Handler :~> EitherT ServantErr IO)
+-- ^ Servant requires its handlers to be 'EitherT ServantErr IO'
+--
+-- This generates a 'Nat'ural transformation for squashing the monad-transformer-stack we use in our handlers to the monad 'servant-server' wants
 handlerNat = do
   sqlPool <- ask
   logFunc <- askLoggerIO
@@ -54,6 +58,7 @@ handlerNat = do
   return $ hoistNat protoNat
 
 thermoprintServer :: ServerT ThermoprintAPI Handler
+-- ^ A 'servant-server' for 'ThermoprintAPI'
 thermoprintServer = listPrinters
                      :<|> (listJobs :<|> queueJob)
                      :<|> getJob <||> jobStatus <||> deleteJob
-- 
cgit v1.2.3