From 0ffe520c6015e5f84e14b48ab93c43501a8d4ce1 Mon Sep 17 00:00:00 2001
From: codygman <cody@codygman.dev>
Date: Sun, 21 Jun 2020 09:35:31 -0500
Subject: [PATCH 1/3] make new user experience smoother

This adds some noise, which I'm not a huge fan of. However if I hadn't
had my cup of coffee and not tried reading the type error, I might have
pushed back "actually use polysemy in the real world" to "later".

Ideally I think I would have read the docs, but I suspect that "paste
examples verbatim into ghc source file without reading docs" is a
popular method to try libraries out.

Fixes #349
---
 src/Polysemy/Internal.hs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/Polysemy/Internal.hs b/src/Polysemy/Internal.hs
index 681b6bf8..2e9ad056 100644
--- a/src/Polysemy/Internal.hs
+++ b/src/Polysemy/Internal.hs
@@ -113,6 +113,7 @@ import Polysemy.Internal.Union
 --   example
 --     & runError
 --     & fmap (either id id)
+--     -- Without `-fplugin=Polysemy.Plugin` you need `evalState @String`
 --     & evalState ""
 --     & runM
 --     & (print =<<)
@@ -123,6 +124,7 @@ import Polysemy.Internal.Union
 --
 -- >>> :{
 --   example
+--     -- Without `-fplugin=Polysemy.Plugin` you need `evalState @String`
 --     & evalState ""
 --     & runError
 --     & fmap (either id id)

From d558d1e74e0b8725eafd4dac8f3d9c9cf1858b24 Mon Sep 17 00:00:00 2001
From: codygman <cody@codygman.dev>
Date: Sun, 21 Jun 2020 09:44:01 -0500
Subject: [PATCH 2/3] remove type application in example

I think the thought here is to assume the plugin is used. If that's the
case, at least on ghc 8.8.3, the type application isn't needed on catch
with polysemy-plugin enabled.

Added comment about needing type application without the plugin in line
with the reason for this PR for users who might just copy/paste to try polysemy.
---
 src/Polysemy/Internal.hs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Polysemy/Internal.hs b/src/Polysemy/Internal.hs
index 2e9ad056..ba0e79f3 100644
--- a/src/Polysemy/Internal.hs
+++ b/src/Polysemy/Internal.hs
@@ -103,7 +103,8 @@ import Polysemy.Internal.Union
 --         catching = do
 --           modify (++"-catch")
 --           get
---     catch @String throwing (\ _ -> catching)
+--     -- Without `-fplugin=Polysemy.Plugin` you need `catch @String`
+--     catch throwing (\ _ -> catching)
 -- :}
 --
 -- when handling 'Polysemy.Error.Error' first, state is preserved after error

From 80ee27baa6b6b91e9c285ff377452a4ea5cac6f0 Mon Sep 17 00:00:00 2001
From: codygman <cody@codygman.dev>
Date: Sun, 21 Jun 2020 09:57:26 -0500
Subject: [PATCH 3/3] add note about BlockArguments

One could assume that after clicking through to
"necessary-language-extensions" and pasting the list in:

    - DataKinds
    - FlexibleContexts
    - GADTs
    - LambdaCase
    - PolyKinds
    - RankNTypes
    - ScopedTypeVariables
    - TypeApplications
    - TypeOperators
    - TypeFamilies

That you'd be done with adding language extensions. That's the mistake I
just made anyway :)

This is just a note to help others avoid that mistake.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f54de45f..c124e246 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ will be true in GHC 8.10.1.
 ## Examples
 
 Make sure you read the [Necessary Language
-Extensions](https://github.com/isovector/polysemy#necessary-language-extensions)
+Extensions](https://github.com/isovector/polysemy#necessary-language-extensions) and add any extras in example source blocks (such as LambdaCase and BlockArguments below)
 before trying these yourself!
 
 Teletype effect: