docs: add haddock documentation

Author: drlkf

src/Control/Carrier/Logger/IO.hs

@@ -7,10 +7,19 @@
 {-# LANGUAGE TypeOperators #-}
 {-# LANGUAGE UndecidableInstances #-}
 
+-- | An IO carrier for the 'Logger' effect that writes logs to a 'Handle'
+-- selected by the provided function.
 module Control.Carrier.Logger.IO (
+  LoggerIOC (LoggerIOC),
+
+  -- * Helpers
   HandleSelector,
   singleHandle,
+
+  -- * Carrier implementation
   runLoggerIO,
+  runStdoutLoggerIO,
+  runStderrLoggerIO,
 ) where
 
 import Control.Algebra (Algebra (..), (:+:) (..))
@@ -28,7 +37,7 @@ import Control.Monad.Logger (
   fromLogStr,
  )
 import qualified Data.ByteString.Char8 as B (hPutStr)
-import System.IO (Handle)
+import System.IO (Handle, stderr, stdout)
 
 -- | Algebra for a simple IO logger. The inner function allows for selecting a
 -- 'Handle' according to something like 'LogLevel'.
@@ -39,7 +48,10 @@ newtype LoggerIOC f m a = LoggerIOC
 
 type HandleSelector = Loc -> LogSource -> LogLevel -> LogStr -> Handle
 
-singleHandle :: Handle -> HandleSelector
+-- | Helper to run IO loggers by writing to the same 'Handle' every time.
+singleHandle
+  :: Handle
+  -> HandleSelector
 singleHandle h _ _ _ _ = h
 
 instance
@@ -60,9 +72,22 @@ instance
           )
     R other -> LoggerIOC (alg (runLoggerIOC . hdl) (R other) ctx)
 
--- | Run a logger by writing to a 'Handle'.
+-- | Run logger, writing to a 'Handle' selected by a function @f@.
 runLoggerIO
   :: HandleSelector
+  -- ^ @f@
   -> LoggerIOC HandleSelector m a
   -> m a
 runLoggerIO f = runReader f . runLoggerIOC
+
+-- | Run logger, writing everything to 'stdout'.
+runStdoutLoggerIO
+  :: LoggerIOC HandleSelector m a
+  -> m a
+runStdoutLoggerIO = runLoggerIO (singleHandle stdout)
+
+-- | Run logger, writing everything to 'stderr'.
+runStderrLoggerIO
+  :: LoggerIOC HandleSelector m a
+  -> m a
+runStderrLoggerIO = runLoggerIO (singleHandle stderr)

src/Control/Carrier/Logger/Writer.hs

@@ -7,6 +7,11 @@
 {-# LANGUAGE TypeOperators #-}
 {-# LANGUAGE UndecidableInstances #-}
 
+-- | A pure carrier for the 'Logger' effect, using an underlying 'Writer'
+-- effect.
+--
+-- >>> length (fst (run (runLoggerW (logDebugN "1" >> logDebugN "2" >> logWarnN "3"))))
+-- 3
 module Control.Carrier.Logger.Writer (
   LoggerWriterC (..),
   runLoggerW,

src/Control/Effect/Logger.hs

@@ -4,6 +4,9 @@
 {-# LANGUAGE UndecidableInstances #-}
 {-# OPTIONS_GHC -Wno-orphans #-}
 
+-- | A simple logger effect that takes all the information a 'MonadLogger' monad
+-- would take. Use the logging functions of 'MonadLogger' to log things the way
+-- you want, as there are many options there (TH or non-TH).
 module Control.Effect.Logger (
   Logger (..),
 ) where
@@ -18,15 +21,8 @@ import Control.Monad.Logger (
  )
 import Data.Kind (Type)
 
---
--- Effect definition
---
-
--- | A simple logger effect that takes all information a 'MonadLogger' monad
--- would take. In order to be able to use the same interface as 'MonadLogger',
--- that unfortunately means it needs to implement the 'MonadLogger' instance as
--- an orphan.
 data Logger (m :: Type -> Type) k where
+  -- | See 'monadLoggerLog'.
   LoggerLog
     :: ToLogStr msg
     => Loc
@@ -35,6 +31,7 @@ data Logger (m :: Type -> Type) k where
     -> msg
     -> Logger m ()
 
--- ORPHAN :(
+-- | Unfortunately, we need to implement the 'MonadLogger' instance as an orphan
+-- in order to be able to use the same interface as 'MonadLogger'.
 instance (Has Logger sig m, Monad m) => MonadLogger m where
   monadLoggerLog loc src lvl msg = send (LoggerLog loc src lvl msg)