From 97e0f527da02507bc5d577fb4d402859e909ce1c Mon Sep 17 00:00:00 2001
From: Tom Ellis <tom-git@jaguarpaw.co.uk>
Date: Sat, 10 Feb 2024 11:50:14 +0000
Subject: [PATCH] More docs

---
 bluefin-internal/src/Bluefin/Internal.hs | 39 +++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/bluefin-internal/src/Bluefin/Internal.hs b/bluefin-internal/src/Bluefin/Internal.hs
index 9c2a993..b850aa3 100644
--- a/bluefin-internal/src/Bluefin/Internal.hs
+++ b/bluefin-internal/src/Bluefin/Internal.hs
@@ -134,6 +134,13 @@ instance (e :> es) => e :> (x :& es)
 -- | @e@ is a subset of a larger set @e :& es@
 instance {-# INCOHERENT #-} e :> (e :& es)
 
+-- |
+-- @
+-- >>> runEff $ try $ \\e -> do
+--       throw e "Exception thrown"
+--       pure "No exception thrown"
+-- Left "Exception thrown"
+-- @
 throw ::
   (ex :> effs) =>
   Exception e ex ->
@@ -142,6 +149,11 @@ throw ::
   Eff effs a
 throw (Exception throw_) e = Eff (throw_ e)
 
+throwExample :: Either String String
+throwExample = runEff $ try $ \e -> do
+  _ <- throw e "Exception thrown"
+  pure "No exception thrown"
+
 has :: forall a b. (a :> b) => a `In` b
 has = In# (# #)
 
@@ -179,6 +191,13 @@ catch ::
   Eff effs a
 catch f h = handle h f
 
+-- |
+-- @
+-- >>> runEff $ runState 10 $ \\st -> do
+--       n <- get st
+--       pure (2 * n)
+-- (20,10)
+-- @
 get ::
   (st :> effs) =>
   State s st ->
@@ -186,15 +205,33 @@ get ::
   Eff effs s
 get (State r) = Eff (readIORef r)
 
+exampleGet :: (Int, Int)
+exampleGet = runEff $ runState 10 $ \st -> do
+  n <- get st
+  pure (2 * n)
+
 -- | Set the value of the state
+--
+-- @
+-- >>> runEff $ runState 10 $ \\st -> do
+--       put st 30
+--       pure ()
+-- ((), 30)
+-- @
 put ::
   (st :> effs) =>
   State s st ->
-  -- | The new value of the state
+  -- | The new value of the state.  The new value is forced before
+  -- writing it to the state.
   s ->
   Eff effs ()
 put (State r) !s = Eff (writeIORef r s)
 
+examplePut :: ((), Int)
+examplePut = runEff $ runState 10 $ \st -> do
+  put st 30
+  pure ()
+
 modify ::
   (st :> effs) =>
   State s st ->