additional documentation

2 files changed, 9 insertions, 3 deletions

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