Update docs for runTH and bindTH #394
Conversation
googleson78
force-pushed
the
interpreth-combinators-docs
branch
2 times, most recently
from
0ff181e to
b17f661
Compare
| -- @ | ||
| -- | ||
| -- The @f@ type here is existential and corresponds to "whatever |
There was a problem hiding this comment.
Unfortunately there is no long an example to attach this talking point to, and it seems rather important, as it explains the that a forall f. Functor f => f ... is being used as "state".
Is there some other example that can be given here to demonstrate this? @KingoftheHomeless @tek @TheMatten
There was a problem hiding this comment.
can't we just put it at the end of the doc comment, so that the association with the type decl is apparent?
There was a problem hiding this comment.
ok obviously that should be "top of the comment" 😄
in any case, the first sentence mentions "threading the state", so it might be sensible to just expand on that there
There was a problem hiding this comment.
Added it back near the top + another piece of documentation that I previously deleted
googleson78
force-pushed
the
interpreth-combinators-docs
branch
4 times, most recently
from
37e4aa9 to
f65eb9c
Compare
|
Here's a screen of the rendered thing |
We now have runTSimple and bindTSimple and should recommend them to users.
googleson78
force-pushed
the
interpreth-combinators-docs
branch
from
f65eb9c to
b5d6ee6
Compare
| @@ -28,8 +28,15 @@ import Polysemy.Internal.Union | |||
| -- effect @Tactics@, which is capable of rewriting monadic actions so they run | |||
| -- in the correct stateful environment. | |||
| -- | |||
| -- Inside a 'Tactical', you're capable of running 'pureT', 'runT' and 'bindT' | |||
| -- which are the main tools for rewriting monadic stateful environments. | |||
| -- The @f@ type here is existential and corresponds to "whatever | |||
There was a problem hiding this comment.
I added the "existential" comment back here.
| -- The @f@ type here is existential and corresponds to "whatever | ||
| -- state the other effects want to keep track of." @f@ is always | ||
| -- a 'Functor'. | ||
| -- Note that because of the types of @'bindTSimple' use resource@ and @'bindTSimple' dealloc resource@ |
There was a problem hiding this comment.
I also add this "same environment" comment back here.
There was a problem hiding this comment.
Haddock rendering doesn't do a great job of distinguishing @@ blocks from normal text..
| -- 'Polysemy.Resource.Bracket' alloc dealloc use -> do | ||
| -- resource <- 'runTSimple' alloc | ||
| -- result <- 'bindTSimple' use resource | ||
| -- 'bindTSimple' dealloc resource |
There was a problem hiding this comment.
This is wrong, since this will have dealloc inherit the state from alloc and not result.
The "proper" solution would be:
fresource <- runTSimple alloc
fresourceresult <- bindTSimple (\a -> ((,) a) <$> use a) fresource
bindTSimple (\(resource, result) -> result <$ dealloc resource) fresourceresultThis is very complicated. Also, this documentation is misleading since this isn't actually how runResource is implemented; it does some extra stuff like using the inspector to check if use failed.
All in all, we should pick a different example than Resource.
There was a problem hiding this comment.
Hm, does the current example do the same thing regarding the "state inheritance"? This is the impression I was left with (and it also seems to be the point of the example), from the current documentation.
I guess it would be misleading if the actual runResource runs in a different way.
|
Subsumed by #422 (since all of these functions are going bye-bye.) Closing, but feel free to open if you feel like it! |
No description provided.