Write documentation for ContT

[cb372]

Had a crack at writing some documentation for ContT.

Corrections/suggestions welcome.

[codecov-io]

Codecov Report

Merging #2677 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2677   +/-   ##
=======================================
  Coverage   95.13%   95.13%           
=======================================
  Files         365      365           
  Lines        6757     6757           
  Branches      300      300           
=======================================
  Hits         6428     6428           
  Misses        329      329

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 76704df...a45f83e. Read the comment docs.

[kailuowang]

Thanks so much, @cb372. Our users can certainly use some documentation on this one. I think this draft explained well how to use it. There are a couple of points that not obvious to me and possibly other readers with no experience with ContT.

• for chaining computations, can we document the benefits of flatMaping a chain of A => ContT over andThening a chain of Kleisli?
• less importantly, it seems a bit redundant that ContT.apply ask for a (B => M[A]) => M[A]) while user just computes a B and call the B => M[A] at the end. Why can't there be a simplified version that takes a => B and construct the (B => M[A]) => M[A]) for user? something like

def defer[M[_], A, B](b: => B): ContT[M, A, B] =  apply(_(b))

I suspect that there must be reason but it's just not obvious to me, and probably worth documenting.

cc @johnynek @djspiewak @Leammas @rossabaker @ceedubs

[djspiewak]

I can’t think of a reason not to have that function. It should work just fine and it sounds quite useful.

[johnynek]

@kailuowang that fuction is hiding there. It is defer(pure(b)). We can certainly add a helper method for it.

By hiding I mean you can use Defer and Applicative to make this function.

It didn’t occur to me. Sorry.

[cb372]

OK, I'll submit a separate PR to add that helper function. It does sounds useful. Once that's merged and released, we can update this documentation to use it.

It's worth pointing out that the apply function is still necessary to cater for slightly more exotic use cases of ContT in which you use the continuation to fill in a "hole" somewhere in the middle of your function, rather than at the end. e.g.

ContT.apply { hole =>
  for {
    a <- doFirstThing()
    b <- doSecondThing(a)
    c <- hole(b)
    d <- doFourthThing(c)
  } yield d
}

(Gabriel Gonzalez goes into more detail in this blogpost.)

As for your first question,

the benefits of flatMaping a chain of A => ContT over andThening a chain of Kleisli?

I don't really have a good answer to that. To be honest, I find the chain of Kleislis easier to follow and I struggled to come up with a motivating example for ContT.

One (rather weak) argument is that ContT acts as a form of documentation, making it explicit that "I'm doing CPS here".

[johnynek]

One thing to note: foreach is a continuation, forall is a continuation, foldMap is a continuation, etc....

Many of our familiar functions take a (A => B) and return a B. This is a continuation. They are holes exactly like the example @cb372 made.

[kailuowang]

Thanks @cb372. Yeah, the original apply is still needed for the hole use case.

[kailuowang]

I propose we get this merged first and we can address the method addition and document update in a separate PR.