How to use free monads in FSharpPlus?

[cmeeren]

(This is briefly mentioned in https://github.com/fsprojects/FSharpPlus/issues/239#issuecomment-576537739.)

I can't see any documentation for free monads in FSharpPlus, other than simple signatures ([1], [2], [3]). I have read this article and I assume that the free monad implementation in FSharpPlus gets rid of some of that boilerplate, but I have absolutely no idea how it works, since there is no code that shows it.

Could the docs be extended with a free monad example? Alternatively (as a temporary measure), can someone post a quick example here about how free monads work in FSharpPlus and how it relates to the approach in the article mentioned above?

[wallymathieu]

If we look in the tests we find the following example:

https://github.com/fsprojects/FSharpPlus/blob/3fdc13372d05c388e8e3f3f9d53ee197230bf526/tests/FSharpPlus.Tests/Free.fs#L74-L144

There is currently not that much in the free monad docs section, but that could change 😉

[gusty]

Yes, what you are requesting it's already in the tests.

There you see some examples taken from some blog posts, if you follow the link of the original blog, you'll see how all the boilerplate that is suppressed.

But yes, ideally this should be somehow in the docs as well, it's not evident that you should dig into the test to find an explanation.

Here there are 2 common issues:

1 - Duplication between tests and docs. The way to sort this out is to compile the docs and move the demonstration piece of code to the docs. I think we are already compiling docs, so now it should be fine to do that.

2 - Duplication between F#+ docs and blog posts. I use to say that if we go deeper in adding deep explanations to all the concepts behind the different abstractions, we'll end up recreating the F# for fun and profit website. I'm still not clear how to approach this, maybe adding link to blogs, together with a link to a diff, to see how F#+ helps to code there.

[cmeeren]

Duplication between F#+ docs and blog posts.

I don't think duplication in documentation is a bad thing. DRY is for code; for documentation and tutorials, it's often better to hammer the points home by repetition and by explaining the same thing in different ways, whether in a single doc/tutorial or by different authors in different contexts.

Take the Elmish ecosystem, for example. The Elm architecture is explained nicely by the official Elm documentation. Despite this, you can also find a short guide in the Elmish docs, a gentle introduction as part of the Elmish.WPF tutorial, and a more thorough introduction/tutorial/walkthrough in The Elmish Book. The core MVU concepts are explained in all of these resources, but they are explained in different ways by different authors.

Personally I think that the F#+ docs are a place where significant improvements can be made to the total usage experience of F#+. Now, I'm of course not not saying that the F#+ documentation should be a complete intro to category theory, or even explain just free monads from the ground up. It's fine to link to other good resources, such as the blog posts of Mark Seemann and Scott Wlaschin. Also, there's the problem of capacity. I know all to well that I don't have the capacity to work as extensively as I'd like on my own OSS projects (whether documentation or code). But IMHO the docs are (perhaps counter-intuitively) one of the most important pieces of any library/framework, particularly those as complicated as F#+.

I think F#+ is an excellent library, and can serve as a gateway to more higher-level functional F# approaches. At least it does for me (I frequently use the generic traverse operator and do not in any way miss writing custom, specific helpers such as Option.traverseAsync etc.). But currently, due to missing docs, the target group of users seem to be those who already know their CT, which I only partly do, so a lot of the F#+ API is "closed off" to me because 1) I don't know what it does, and 2) therefore I don't know how it would help me, hence I don't prioritize digging to deeply into it. (Given infinite time I'd do it of course, but alas, no such thing exists.)

In any case, I'd appreciate a lot if the examples that now reside in the tests could be brought "into the light" as it were in the docs. I don't think anyone should be expected to dig around in the tests in order to find out how to use the package, because tests are often not created to be readable or demonstrate a high-level use-case. A temporary solution could be to have the docs docs specifically refer to a particular test for a demonstration. That's just a quick-and-dirty alternative to embedding code, after all. :)

[wallymathieu]

Yes, I think having links to blogs would be helpful. Though we might need some minimal docs on how to get started rather than having hard to maintain docs resembling blog posts.

[gusty]

@cmeeren Yes, we could afford the duplication, but as you said it's a lot of effort. Anyway, we should do something, at least minimal, at the moment not even the links are there.

Regarding the tests, as I said before: now those tests can be moved to the docs, no need to duplicate them, as the docs are checked for compilation. I will take care of it.

[gusty]

We added docs in https://fsprojects.github.io/FSharpPlus/type-free.html with links to some excellent blogs, I recommend the first one, which has a very good explanation and uses F#+

Hopefully this close the issue about how to use it. Otherwise feel free to reopen.