StateT Documentation

[benkio]

Add StateT documentation Page to the microsite
Update the latest cats version in README.md
Minor source path fix

Linked to #1801

[armanbilge]

Thanks for the PR and fixes!

The in-depth example for StateT is fantastic but not sure about using Eval as a hack to suspend side-effects without IO. Instead could we use a monad like Writer to "print" to a List[String]? WDYT?

[benkio]

Thanks for the PR and fixes!

The in-depth example for StateT is fantastic but not sure about using Eval as a hack to suspend side-effects without IO. Instead, could we use a monad like Writer to "print" to a List[String]? WDYT?

Hi There,
I'm glad you like the example 😄
I choose Eval over other options because:

• IO is not in scope
• Eval is used in State as well and is fairly simple to understand

Writer can be used as an alternative, but then the reader needs to know it (and maybe WriterT) in order to fully understand the example. I found Eval more straightforward compared to it and since StateT is closely related to State, there's a high chance that the reader knows it already. However, if more people likes Writer more, I'm happy to do the change. It was a stylistic choice 😅
Finally, I could have used Future as others had done throughout the docs as effectful type, I think it should be considered as an option as well.
I'll wait for more input on the matter 👍

[armanbilge]

Thanks for the detailed explanation :)

It was a stylistic choice 😅

I appreciate that :) unfortunately, it's a stylistic choice with practical implications. Using Eval for println or indeed to suspend any side-effect is not generally accepted and is something I think we should avoid demonstrating in docs. See typelevel/cats-effect#78 (comment) for discussion.

Future is similarly controversial, see #2334.

So my vote is for Writer or similar, although for sure let's give others a chance to chime in.

[armanbilge]

Thanks for the revisions!

[armanbilge]

Would you consider contributing this example to the Cats Effect docs? :) I think it would be cool!

[benkio]

I agree. I looked quickly at the cats-effects doc site, but it's not structured in the same way as this one. I struggle to identify where we can put general IO examples like the hangman one.

What I would like more is to extend the example folder in the repo(or have a separate repo) with more use cases like this one, so newcomers can go, grab the code or just check it out easily. This also applies to cats, http4s, fs2...Some of them have some examples, but there's nothing structured, like the TypelevelExamples repo for instance. This sounds more like a Megathread proposal 😅

[armanbilge]

That's true, I guess we'd have to add an "examples" section to the cats-effect docs. Hum.

Yes, this is totally a mega-thread issue :) Probably we need a unified Typelevel docs site + examples repo, that can show examples using multiple projects together, like cats and cats-effect. There are already a few projects for this purpose, like https://github.com/djspiewak/kitteh-redis.

I know the typelevel.org website is currently being redesigned and I had some ideas in typelevel/governance#28 that maybe we can raise some funding for improving documentation as well. Feel free to comment there or raise an issue about this topic since you seem passionate about it :)

[benkio]

I'll definitely have a look there 😉

Passionate...I'm just a lazy coder who likes to copy-paste code 😝 That's why I like the examples repo idea.

Another option, instead of having a typelevel repo for examples, could be to just have a page where we collect links from individual public repositories/gists examples, like the redis above.

Pro: the maintenance is not on typelevel specifically, we just have to be sure the repos are still there and it can be done programmatically + it's faster to setup, I'm quite sure there are already tons of existing examples on Github.

Cons: we don't have control over the "working condition" of such examples, but we have to trust the developer who built them.

Basically, at the end of the day, it will be very similar to the Typelevel Ecosystem page we already have, but for examples instead of libraries.

PS: we can also think of referring to a specific section of a larger project: "package for the http4s API of lib XYZ..."

[armanbilge]

Thanks, good ideas there! Once the new website lands we can try and find a home for these :)

[armanbilge]

Thanks, just a few comments, I think it's in pretty good shape! :)

[armanbilge]

Can we change up the reservations? Children's characters are always nice. Madeline, Elmo, Winnie-the-Pooh, etc. :)

[armanbilge]

Thanks for all your hard work on this! This is a very nice contribution :)