Add documentation for `Bimonad` #4076

gatear · 2021-12-08T15:18:18Z

The first draft for Bimonad docs as required in #1801
Couldn't find a better example .. i'm open to suggestions.

docs/src/main/mdoc/typeclasses/bimonad.md

armanbilge · 2021-12-09T13:09:32Z

docs/src/main/mdoc/typeclasses/bimonad.md

+
+The `Bimonad` trait directly extends `Monad` and `Comonad` without introducing new behaviour. `Bimonad` is 
+different of other `Bi` typeclasses like `Bifunctor`, `Bifoldable` or `Bitraverse` where the prefix describes a
+`F[_, _]`. The `Bimonad` is a `F[_]` and could be better seen as a dual monad i.e. something that is both a `Monad` and 


"dual monad" is another one that I worry is confusing. For one, Comonad is not a Monad. Actually it is the dual of Monad!
https://typelevel.org/cats/typeclasses/comonad.html

The DualMonad\SelfDualMonad thing i picked from old issues like #1297

I'll change it to:

The `Bimonad` is a `F[_]` and the `Bi` prefix has a different meaning here: it's both a `Monad` and a `Comonad`.

docs/src/main/mdoc/typeclasses/bimonad.md

armanbilge · 2021-12-09T13:14:23Z

docs/src/main/mdoc/typeclasses/bimonad.md

+import cats.data._
+import cats.implicits._
+
+Bimonad[Eval].pure(true).extract === Eval.now(true).value


I think what you are trying to show here is that pure is implemented as now and extract as value? One alternative would be to define Bimonad[Eval] here just for demonstrative purposes, WDYT?

I think what you are trying to show here is that pure is implemented as now and extract as value?

Yes

One alternative would be to define Bimonad[Eval] here just for demonstrative purposes, WDYT?

Something like that ?

val evalBimonad = Bimonad[Eval] evalBimonad.pure(true).extract === Eval.now(true).value

I was thinking like how they define optionMonad in the Monad docs:
http://typelevel.org/cats/typeclasses/monad.html

docs/src/main/mdoc/typeclasses/bimonad.md

armanbilge

Thanks for the contribution! :)

johnynek · 2021-12-09T17:48:02Z

docs/src/main/mdoc/typeclasses/bimonad.md

+import cats.implicits._
+
+implicit def evalBimonad(implicit monad: Monad[Eval], comonad: Comonad[Eval]) =
+  new Bimonad[Eval] {


Eval[_] is a bit of a bad choice here because the Comonad is not very safe. Calling .value on an Eval must be done with some care (it needs to be at O(1) stack depth or you lose the stack safety. If you are calling this as part of a recursive call it often blows up).

Id[_] is also a Comonad, but a bit of a boring one. I wonder if NonEmptyList[_] would be a better example since it is non-trivial but also not somewhat unsafe in this way.

Hm ok, I was hesitating between Eval[_] and NonEmptyList[_] for the main example.
I'll just use NonEmptyList[_].

armanbilge · 2021-12-09T20:15:36Z

docs/src/main/mdoc/typeclasses/bimonad.md

-    //use the coflatMap from the Eval comonad
-    override def coflatMap[A, B](fa: Eval[A])(f: Eval[A] => B): Eval[B] =
+    //use the coflatMap from the NonEmptyList comonad
+    override def coflatMap[A, B](fa: NonEmptyList[A])(f: NonEmptyList[A] => B): NonEmptyList[B] =
      comonad.coflatMap(fa)(f)


Actually we can directly call flatMap and coflatMap directly on the NonEmptyList :)

I was hopping this shows flatMap and coflatMap as originating from monad and comonad.
Don't you think it's a good idea to delegate to the monad and comonad variables ?

Yes, I do see that now. But then isn't it confusing, because pure and extract are also defined in monad and comonad, so we should delegate those as well?

Good point.
I thought using one and head in the implementation will make this more obvious:

nelBimonad.pure(true).extract === NonEmptyList.one(true).head

I thought using one and head in the implementation will make this more obvious

I agree, I think this is the right way to do it. So, we can just delegate flatMap and coflatMap to the list without monad/comonad and maybe leave tailRecM as an exercise for the reader 😉

Anyway just my opinion, not really sure what the best thing to do here is. But I think separating the implementations of pure and extract makes it seem like they are inconsistent or different from the definitions in monad or comonad.

So the current tailRecM implementation for NonEmptyList[_] doesn't look trivial .. I mean I fear Its understanding detours too much and I agree it's a good idea to leave it as an exercise 👍

Anyway just my opinion, not really sure what the best thing to do here is. But I think separating the implementations of pure and extract makes it seem like they are inconsistent or different from the definitions in monad or comonad.

Yes, I will remove monad and comonad.

…NEL `flatMap` and `coflatMap`

armanbilge · 2021-12-10T14:27:48Z

docs/src/main/mdoc/typeclasses/bimonad.md

+### NonEmptyList as a Bimonad
+`NonEmptyList[_]` is a lawful `Bimonad` so you can chain computations (like a `Monad`) and `extract` the result at the end (like a `Comonad`).
+
+Here is a possible implementation based on existing monad and comonad:


Suggested change

Here is a possible implementation based on existing monad and comonad:

Here is a possible implementation:

armanbilge · 2021-12-10T14:54:47Z

docs/src/main/mdoc/typeclasses/bimonad.md

+implicit def nelBimonad =
+  new Bimonad[NonEmptyList] {
+
+    //use NonEmptyList specific methods for creation and extraction


Maybe a good place to point out the Bimonad law about the relationship between pure and extract? :)

//in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`

Something like this ?

armanbilge

Thanks for iterating on all the feedback! Looking good, just a couple tiny things :)

armanbilge · 2021-12-12T19:32:43Z

docs/src/main/mdoc/typeclasses/bimonad.md

+implicit def nelBimonad =
+  new Bimonad[NonEmptyList] {
+
+    //in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`


Just a personal style nitpick but I prefer a space here between // and the comment 😅

Suggested change

//in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`

// in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`

armanbilge · 2021-12-12T19:34:32Z

docs/src/main/mdoc/typeclasses/bimonad.md

+keep in mind `Bimonad` has its own added laws so something that is both monadic
+and comonadic may not necessarily be a lawful `Bimonad`.


I think this is important enough to include at the beginning ...

armanbilge · 2021-12-12T19:35:08Z

docs/src/main/mdoc/typeclasses/bimonad.md

+The `Bimonad` trait directly extends `Monad` and `Comonad` without introducing new methods. `Bimonad` is
+different from other `Bi` typeclasses like `Bifunctor`, `Bifoldable` or `Bitraverse` where the prefix describes a
+`F[_, _]`. The `Bimonad` is a `F[_]` and the `Bi` prefix has a different meaning here: it's both a `Monad` and a `Comonad`.
+


... like this:

Suggested change

Keep in mind `Bimonad` has its own added laws so something that is both monadic

and comonadic may not necessarily be a lawful `Bimonad`.

armanbilge

Thanks for your contribution! :)

gatear · 2021-12-14T10:19:35Z

@armanbilge is this ready to merge or do i need 2 reviews ? I want to start working on another doc for Bifoldable after this one is merged

armanbilge · 2021-12-14T12:40:00Z

Another pair of eyes is always good, maybe @johnynek can take another look at the next opportunity :)

johnynek · 2021-12-21T21:29:37Z

docs/src/main/mdoc/typeclasses/bimonad.md

+
+If you use `Bimonad` as a convenience type such that:
+```scala
+def f[T[_] : Monad, Comonad, S](fa: T[S]): S


I think this should be def f[T[_]: Monad: Comonad, S](fa: T[S]): S

I think the comma here is makingComonad just a type parameter.

Yep my bad ..:Monad :Comonad is what I wanted

johnynek · 2021-12-21T21:30:08Z

docs/src/main/mdoc/typeclasses/bimonad.md

+```
+is re-written to:
+```scala
+def f[T[_] : Bimonad, S](fa: T[S]): S


nit: we generally don't put a space after the type, so we would change to: f[T[_]: Bimonad, S]

johnynek · 2021-12-21T21:30:36Z

docs/src/main/mdoc/typeclasses/bimonad.md

+import cats.data._
+import cats.implicits._
+
+implicit def nelBimonad =


I would make this a implicit val since it doesn't have any args.

johnynek · 2021-12-24T18:28:49Z

Thanks!

gatear added 3 commits December 8, 2021 17:00

Add Bimonad doc

9adfc5e

Merge https://github.com/typelevel/cats into bimonad-docs

5d0d8ef

Fix typo in mdoc title

0a4ea09

gatear mentioned this pull request Dec 8, 2021

Documentation megathread #1801

Open

70 tasks

gatear changed the title ~~Bimonad docs~~ Add documentation for Bimonad Dec 8, 2021

Add imports

030405c

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

docs/src/main/mdoc/typeclasses/bimonad.md Outdated Show resolved Hide resolved

armanbilge reviewed Dec 9, 2021

View reviewed changes

address comments from @armanbilge

d4d97b2

gatear force-pushed the bimonad-docs branch from 5b69701 to d4d97b2 Compare December 9, 2021 14:55

Define an Eval bimonad

3f7180a

gatear requested a review from armanbilge December 9, 2021 15:45

johnynek reviewed Dec 9, 2021

View reviewed changes

Swap Eval[_] with NonEmptyList[_] for the main example

687dd0b

gatear requested a review from johnynek December 9, 2021 20:10

armanbilge reviewed Dec 9, 2021

View reviewed changes

Leave tailRecM implementation as an exercise and delegate to input …

ea8322d

…NEL `flatMap` and `coflatMap`

gatear requested a review from armanbilge December 10, 2021 11:38

armanbilge reviewed Dec 10, 2021

View reviewed changes

Use first bimonad law in implementation comments

0ab5e3f

gatear requested a review from armanbilge December 10, 2021 16:36

armanbilge reviewed Dec 12, 2021

View reviewed changes

address comments from @armanbilge

2923299

armanbilge previously approved these changes Dec 13, 2021

View reviewed changes

johnynek reviewed Dec 21, 2021

View reviewed changes

address comments from @johnynek

896b945

gatear dismissed armanbilge’s stale review via 896b945 December 24, 2021 11:34

johnynek approved these changes Dec 24, 2021

View reviewed changes

johnynek merged commit a818296 into typelevel:main Dec 24, 2021

gatear mentioned this pull request Jan 12, 2022

Make Bifoldable docs #4109

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for `Bimonad` #4076

Add documentation for `Bimonad` #4076

gatear commented Dec 8, 2021 •

edited

armanbilge Dec 9, 2021

gatear Dec 9, 2021 •

edited

armanbilge Dec 9, 2021

gatear Dec 9, 2021 •

edited

armanbilge Dec 9, 2021

armanbilge left a comment

johnynek Dec 9, 2021

gatear Dec 9, 2021

armanbilge Dec 9, 2021

gatear Dec 9, 2021

armanbilge Dec 9, 2021

gatear Dec 9, 2021

armanbilge Dec 9, 2021

gatear Dec 10, 2021

armanbilge Dec 10, 2021

armanbilge Dec 10, 2021

gatear Dec 10, 2021 •

edited

armanbilge left a comment

armanbilge Dec 12, 2021

armanbilge Dec 12, 2021

armanbilge Dec 12, 2021

armanbilge left a comment

gatear commented Dec 14, 2021

armanbilge commented Dec 14, 2021

johnynek Dec 21, 2021

gatear Dec 24, 2021

johnynek Dec 21, 2021

johnynek Dec 21, 2021

johnynek commented Dec 24, 2021

	Here is a possible implementation based on existing monad and comonad:
	Here is a possible implementation:

	//in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`
	// in order to have a lawful bimonad `pure` and `extract` need to respect: `nelBimonad.extract(nelBimonad.pure(a)) <-> a`

		keep in mind `Bimonad` has its own added laws so something that is both monadic
		and comonadic may not necessarily be a lawful `Bimonad`.

Add documentation for Bimonad #4076

Add documentation for Bimonad #4076

Conversation

gatear commented Dec 8, 2021 • edited

Choose a reason for hiding this comment

gatear Dec 9, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gatear Dec 9, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

armanbilge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gatear Dec 10, 2021 • edited

Choose a reason for hiding this comment

armanbilge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

armanbilge left a comment

Choose a reason for hiding this comment

gatear commented Dec 14, 2021

armanbilge commented Dec 14, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnynek commented Dec 24, 2021

Add documentation for `Bimonad` #4076

Add documentation for `Bimonad` #4076

gatear commented Dec 8, 2021 •

edited

gatear Dec 9, 2021 •

edited

gatear Dec 9, 2021 •

edited

gatear Dec 10, 2021 •

edited