New user documentation feedback

[tomjaguarpaw]

Some new user feedback

---

"As for learning what learning materials I used and enjoyed I'd say the most useful where:"

1. Get started with Bluefin [YouTube] - This was by far the most useful and after watching and flowing along, I had a general Idea of how to use Bluefin & write basic functions with it.

2. Type Signatures [Docs: Bluefin] - This was a good intro into what a Bluefin function looks like, its very well explained and gives context to the rest of the docs going forward.

   • This should probably be near the top, if not the first thing in the docs IMO, it really sets the stage
   • This one is admittedly a complete preference, but I find it easier to parse the types in a Bluefin function if the arrows are at the start of the new line rather than the end.

3. Exception Handles [Docs: Bluefin] - This was a good introduction to both Bluefin exceptions and Handles in general. It explains what benefits Bluefin has over regular Haskell, which is something I think could be more prevalent throughout the docs/github.

4. Effect Scoping [Docs: Bluefin] - This was also a good explanation but should be the second thing mentioned about bluefin and not in the middle of the docs.

5. Type Inference [Haskell] - Haskell's type inference was constantly steering me the write way when making functions, which shows how good the type system is in Bluefin.

Resources I used but where just ok:

1. Wrap a Single Effect [Docs: Bluefin-Compound] - This was a clear example of wrapping an effect.
   • Overall I'd like more of a context on why creating my own effects would be useful (I'd add context to the explanation)
   • Not necessarily exclusive to this part of the documentation, but it was where I realised that I kinda just wanted some itinerary of all the different Bluefin Handles somewhere.
2. Bluefin IO docs a whole [Docs: Bluefin-IO] - Having the type signature for everything allowed be to intuit a lot, but somethings like effIO I only understood due to external resources.
   • Overall it gives the impression that it is under construction (which it probably is).
3. Wrap Multiple Effects, a better approach [Bluefin-Compound] - I used this in conjunction with the example in your github when making withDB3, it shows how to use useImplIn and mapHandle but does not really elaborate.
4. LSP Integration [Haskell LSP] - Since the majority of functions do not have any explanation of the their purpose and only a type sig, the lsp integration for bluefin felt a little lacking.

Resources which where seemly non-existent:

1. Operators - Although mentioned briefly in Type Signatures (Docs: Bluefin), I felt like operators such as :> and :& could have explanations on what they do in the context of Bluefin.
2. What is an effect system - The documentation draws consistent comparison to Effectful, but as someone still somewhat new to Haskell, I've never used it. A simple explanation of effect systems and their benefits might be useful to some users.

Source: https://old.reddit.com/r/haskell/comments/1kej2qe/a_question_on_idiomatic_early_returns/ms0d4l8/

[ShilohAlleyne]

Hi i'm Shiloh, the original commentor.

If I where to harzard a guess on something which both: "really needs improvement" and "accessible for a Bluefin new user to work on", I'd start with by adding the content from this talk: Comparing Bluefin to Effectful, to the Hoogle documentation. I hadn't watched it at the time of commenting, but covers the following points pretty well:

• Ok Resources: 1 and 2
• Seemingly non-existent Resources: 2

Shiloh

[tomjaguarpaw]

Great, would you like to go ahead and put up a small draft PR that shows an example of the kind of thing you're thinking of?

[ShilohAlleyne]

Awesome, I'll get it done over the weekend!

[tomjaguarpaw]

Bluefin IO docs a whole [Docs: Bluefin-IO] ... somethings like effIO I only understood due to external resources.

Overall it gives the impression that it is under construction (which it probably is).

We should try to improve this, as Bluefin.IO is definitely not "under construction" (at least, it will develop further, but where it is now is intended to be a stable and documented state). @ShilohAlleyne, could you suggest something that could be done to improve the situation here?

For reference: Bluefin.IO documentation.

[ShilohAlleyne]

@tomjaguarpaw

By in large, in think most of my issues with the IO docs where that I felt that there was a lack of context in the explanations. At the time of the comment, I only had a nebulous understanding of the core concepts of Bluefin, I new how to make things work and have the types in my function algin, but there wasn't much of a concept of "why" it works in my head. Most of this should be solved for me (and hopefully other new users) when I finish writing up the Comparing Bluefin to Effectful talk.

That said for things specific to the IO page, I remember having issue with:

• data IOE (e : : Effects): There’d no explanation how bluefin datatypes correspond to effects
• Handle IOE: Handle currently links to class Handle (h : : Effects -> Type) where in Bluefin.Compound, which is an example about defining your own handle in the context of an “Application” which has multiple effects that need to be managed. A singular explanation of Handle and how they tie into Bluefin’s effect system would be better.
• Handlers: A General explanation of Top level effect Handlers such as runEff, runEff_ would be nice.
• runEff: runEff suggests that you should use, runEff_ instead and it also uses runEff_ in its example, this makes the regular runEff feel slightly redundant, and caused be some minor confusion before I eventually just shrugged it off, and used runEff_ as suggested.
• From a technical standpoint everything is good, but as a newbie I felt that the documentation lacked cohesion or context within bluefin.
  • A good example is the simple statement in EffReader, it gives context as to why EffReader exists as it is.
• I'd also love some Bluefin.Compound esq worked examples explicitly for/on the IO page.

Hope this helps, maybe we should pencil this in for something to do after I've written up Comparing Bluefin to Effectful ?

[tomjaguarpaw]

Handle IOE: Handle currently links to class Handle (h : : Effects -> Type) where in Bluefin.Compound, which is an example about defining your own handle in the context of an “Application” which has multiple effects that need to be managed. A singular explanation of Handle and how they tie into Bluefin’s effect system would be better.

Yeah this is a good point. Handle isn't just for user-defined effects. I should add a better explanation.

[tomjaguarpaw]

this makes the regular runEff feel slightly redundant, and caused be some minor confusion before I eventually just shrugged it off, and used runEff_ as suggested.

Yeah, it is redundant and everyone should be using runEff_ instead. Is there a way I can make this clearer?

A good example is the simple statement in EffReader, it gives context as to why EffReader exists as it is.

Ah, that's ironic, because EffReader is one of the least important parts of Bluefin! Could you come up with an equally good explanation for IOE?

Hope this helps, maybe we should pencil this in for something to do after I've written up Comparing Bluefin to Effectful ?

Yeah it's really helpful to share your perspective so I can see what new users need. Thanks!

[KristianAN]

Hi, I'm new to Bluefin and Haskell in general. I tried using Bluefin with Servant for a small project I am doing but gave up as I couldn't find any neat way of integrating the two that didn't involve a lot of boilerplate that I barely understand. I switched to effectful where it was a lot more straight-forward (for me at least).

Bluefin to me looks like it should be more beginner friendly as the value level handlers are more explicit and the compiler errors seem a lot more coherent/helpful with Bluefin. So I guess the point I want to make is that I really wish there was some more examples of how to integrate Bluefin with commonly used Haskell libraries (doesn't have to be Servant, that was just my use-case). I think that would really help people like me grok things.

[tomjaguarpaw]

Thanks! Do you have open source code that shows how you used effectful with Servant? I don't know Servant myself, so might have trouble writing documentation for that unless there's something that already exists that I can copy ...

[ShilohAlleyne]

@KristianAN I've got a few examples of using Bluefin with Servant & Simple.SQLite, since that is what I've been using for my own little project. If you tell me what your pain points where then I can provide examples of how I've tackled them.

For Servant specifically, most of my top level request handlers look like this:

getAllFilesHandler :: Config.Config -> Handler [File]
getAllFilesHandler c = do
    files <- liftIO $ runEff_ $ \io ->
        try $ \ex -> Query.getFiles io ex c

    case files of
        Left err -> throwError err500 { errBody = LBS.pack ("Database error: " <> show err) }
        Right fs -> pure fs

Here we are using :

1. runEff_: to handle the IO effect for our database connection.
2. try: to handle Bluefin exceptions. (In Query.getFiles the handle for the db connection uses rethrowIO to convert Simple.SQLite Errors to Bluefin exceptions)

Doing this, our io effects get proper encapsulated in the request handler.

[KristianAN]

Thanks! Do you have open source code that shows how you used effectful with Servant? I don't know Servant myself, so might have trouble writing documentation for that unless there's something that already exists that I can copy ...

I haven't had time to set up a project for it, but here is a code example of the issues I faced before I switched to effectful. https://gist.github.com/KristianAN/bc52637ae3a81643830dd9fb2cd6ac81

[tomjaguarpaw]

Thanks. Are you looking for a Bluefin equivalent of something like this? That is, run a ServerT that wraps a Bluefin Eff?

runWarpServerSettings
  :: forall (api :: Type) (es :: [Effect])
   . (HasServer api '[], IOE :> es)
  => Warp.Settings
  -> ServerT api (Eff (Error ServerError : es))
  -> Eff es ()
runWarpServerSettings settings =
  runWarpServerSettingsContext @api settings EmptyContext

[KristianAN]

Yes, that was what I was failing to get working with Bluefin

[tomjaguarpaw]

Ah right! Maybe @ShilohAlleyne has an idea? In https://github.com/Kleidukos/servant-effectful/blob/main/src/Effectful/Servant.hs it ultimately comes down to this:

-- | Transform the Eff monad into a servant Handler.
interpretServer :: Env es -> Eff (Error ServerError : es) a -> Servant.Handler a
interpretServer env action = do
  v <- liftIO $ do
    es' <- cloneEnv env
    unEff (runErrorNoCallStack action) es'
  T.liftEither v

I'm not sure what to make of that cloneEnv. It's a bit scary since it suggests that the Bluefin code will run in a thread, and we'll have to make sure we're threadsafe.

The relavent servant function seems to be serveWithContextT:

serveWithContextT :: forall api context m. (HasServer api context, ServerContext context) => Proxy api -> Context context -> (forall x. m x -> Handler x) -> ServerT api m -> Application 

So we need to be confident we can put the right thing in for the (forall x. m x -> Handler x) argument.