A big pass on documentation and interface preparing for release

Closes #14

Author: aspiwack

backends/katip/benign-katip.cabal

@@ -1,12 +1,12 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.35.0.
+-- This file has been generated from package.yaml by hpack version 0.38.0.
 --
 -- see: https://github.com/sol/hpack
 
 name:           benign-katip
 version:        0.1.0
-synopsis:       A library for benign effects
+synopsis:       A Benign backend for the Katip library
 description:    see README.md.
 homepage:       https://github.com/aspiwack/haskell-benign#readme
 bug-reports:    https://github.com/aspiwack/haskell-benign/issues

backends/katip/package.yaml

@@ -4,7 +4,7 @@ author: Arnaud Spiwack
 maintainer: [email protected]
 github: aspiwack/haskell-benign
 copyright: MIT
-synopsis: A library for benign effects
+synopsis: A Benign backend for the Katip library
 description: see README.md.
 
 dependencies:

backends/katip/src/Benign/Katip.hs

@@ -1,6 +1,19 @@
 {-# LANGUAGE GHC2021 #-}
 
-module Benign.Katip where
+-- | This module is a small wrapper around
+-- [Katip](https://hackage.haskell.org/package/katip) to allow logging in pure
+-- code.
+--
+-- The wrapper is a little primitive still and you will have to handle the
+-- transition from IO code to pure code manually. Pull requests are, of course,
+-- welcome.
+module Benign.Katip
+  ( withKatipContext,
+    withKatipNamespace,
+    withKatip,
+    logLocM,
+  )
+where
 
 import Benign qualified
 import GHC.Stack
@@ -28,7 +41,7 @@ withKatipContext item = Benign.withAltering katipContext (<> Just (Katip.liftPay
 withKatipNamespace :: Katip.Namespace -> Benign.Strat a -> a -> a
 withKatipNamespace namespace = Benign.withAltering katipNamespace (<> Just namespace)
 
--- | Within this computation, Katip is configured.
+-- | Within this computation, Katip is configured for pure code.
 withKatip ::
   (Katip.LogItem c) =>
   Katip.LogEnv ->
@@ -42,7 +55,9 @@ withKatip env ctx namespace strat =
     . Benign.withSettingIO' katipContext (Katip.liftPayload ctx)
     . Benign.withSettingIO katipNamespace namespace strat
 
-logLocM :: forall a. (HasCallStack) => Katip.Severity -> Katip.LogStr -> Benign.Strat a -> a -> a
+-- | @'logLocM' s msg a@ logs a an event, like Katip's 'Katip.logLocM', before
+-- evaluating @a@.
+logLocM :: forall a. (HasCallStack) => Katip.Severity -> Katip.LogStr -> a -> a
 logLocM severity str = withFrozenCallStack spanLog
   where
     -- The whole purpose of naming `span` is to freeze the call stack. It's
@@ -53,16 +68,16 @@ logLocM severity str = withFrozenCallStack spanLog
     -- scratch. This would be invisible. I tried to harden this function by
     -- declaring type signatures everywhere. I haven't tested it yet though. It
     -- may be wrong.
-    spanLog :: HasCallStack => Benign.Strat a -> a -> a
-    spanLog = Benign.unsafeSpanBenign doLog (return ())
+    spanLog :: (HasCallStack) => a -> a
+    spanLog = Benign.unsafeSpanBenign doLog (return ()) Benign.whnf
 
-    doLog :: HasCallStack => IO ()
+    doLog :: (HasCallStack) => IO ()
     doLog = do
       -- Making an intermediary `KatipContextT` is a little roundabout, but it's
       -- easier than reaching to Katip's internals.
       --
       -- TODO: catch errors
-      Just env <- Benign.lookupLocalState katipEnv
-      Just ctx <- Benign.lookupLocalState katipContext
-      Just namespace <- Benign.lookupLocalState katipNamespace
+      Just env <- Benign.lookupLexicalState katipEnv
+      Just ctx <- Benign.lookupLexicalState katipContext
+      Just namespace <- Benign.lookupLexicalState katipNamespace
       Katip.runKatipContextT env ctx namespace $ Katip.logLocM severity str

backends/timestats/benign-timestats.cabal

@@ -1,13 +1,13 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.35.0.
+-- This file has been generated from package.yaml by hpack version 0.38.0.
 --
 -- see: https://github.com/sol/hpack
 
 name:           benign-timestats
 version:        0.1.0
-synopsis:       A library for benign effects
-description:    see README.md.
+synopsis:       A Benign backend for the Timestats library
+description:    See the Benign library.
 homepage:       https://github.com/aspiwack/haskell-benign#readme
 bug-reports:    https://github.com/aspiwack/haskell-benign/issues
 author:         Arnaud Spiwack

backends/timestats/package.yaml

@@ -4,8 +4,8 @@ author: Arnaud Spiwack
 maintainer: [email protected]
 github: aspiwack/haskell-benign
 copyright: MIT
-synopsis: A library for benign effects
-description: see README.md.
+synopsis: A Benign backend for the Timestats library
+description: See the Benign library.
 
 dependencies:
   - base

backends/timestats/src/Benign/TimeStats.hs

@@ -7,6 +7,8 @@ import Control.Exception
 import Debug.TimeStats qualified as TimeStats
 import System.IO.Unsafe (unsafePerformIO)
 
+-- | @'measure' label strat thing@ measures, in the style of
+-- 'TimeStats.measurePure', of running @strat thing@.
 measure :: String -> Benign.Strat a -> a -> a
 measure label strat thing = unsafePerformIO $ TimeStats.measureM label $ do Benign.E <- evaluate (strat thing); return thing
 {-# NOINLINE measure #-}

benign.cabal

@@ -1,13 +1,13 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.35.0.
+-- This file has been generated from package.yaml by hpack version 0.38.0.
 --
 -- see: https://github.com/sol/hpack
 
 name:           benign
 version:        0.1.0
 synopsis:       A library for benign effects
-description:    see README.md.
+description:    See the Benign library.
 homepage:       https://github.com/aspiwack/haskell-benign#readme
 bug-reports:    https://github.com/aspiwack/haskell-benign/issues
 author:         Arnaud Spiwack

examples/SimplePrint.hs

@@ -42,7 +42,7 @@ log log_line = Benign.unsafeSpanBenign do_log (return ())
   where
     do_log :: IO ()
     do_log = do
-      ctx <- Benign.lookupLocalState context
+      ctx <- Benign.lookupLexicalState context
       putStrLn (fromMaybe "" ctx ++ " " ++ log_line)
 
 ------------------------------------------------------------------------------

package.yaml

@@ -5,7 +5,7 @@ maintainer: [email protected]
 github: aspiwack/haskell-benign
 copyright: MIT
 synopsis: A library for benign effects
-description: see README.md.
+description: See the Benign library.
 
 dependencies:
   - base