Update docs for runTH and bindTH

src/Polysemy/Internal/Tactics.hs

@@ -38,7 +38,27 @@ import Polysemy.Internal.Union
 -- data 'Polysemy.Resource.Resource' m a where
 --   'Polysemy.Resource.Bracket' :: m a -> (a -> m ()) -> (a -> m b) -> 'Polysemy.Resource.Resource' m b
 -- @
+-- We can interpret this effect like so:
+-- @
+-- 'Polysemy.Resource.Bracket' alloc dealloc use -> do
+--   a <- 'runTH' alloc
+--   res <- 'bindTH' use a
+--   'bindTH' dealloc a
+--   pure res
+-- @
+-- To run the embedded higher-order actions we use 'runTH' for actions
+-- (e.g. @m a@) and 'bindTH' for kleisli actions (e.g. @a -> m b@).
+-- These functions will run the higher-order actions with
+-- \"the current interpreters\" (TODO good explanation on what this means???)
+--
+-- If you want more control over how other potentially embedded
+-- 'Polysemy.Resource.Resource's are run inside your interpeter,
+-- you might want to take a look at 'pureT', 'runT' and 'bindT'.
+-- An example of when you might need them, is when you are interpreting
+-- 'Polysemy.Reader.Local', in which you want to run inner actions
+-- with a modified environment.
 --
+-- TODO modify the section below here?? maybe add the Reader example?
 -- Here we have an @m a@ which clearly needs to be run first, and then
 -- subsequently call the @a -> m ()@ and @a -> m b@ arguments. In a 'Tactical'
 -- environment, we can write the threading code thusly: