Documentation TODO for 3.x

[kanak]

I hope this is OK, but I wanted to capture task ideas from @alexandru and @Avasil in https://github.com/monix/monix.io/pull/28#issuecomment-374912259 in a more visible place and also add a checklist.

• [ ] Observable
• [ ] Iterant (lots of documentation in Scaladocs)
• [ ] Scheduler
  • [ ] clockRealtime / clockMonotonic
  • [ ] TracingScheduler
• [ ] new Task features:
  • [ ] cancelable
  • [ ] uncancelable
  • [ ] onCancelRaiseError
  • [ ] bracket
  • [ ] start + cancel + Fiber
  • [ ] racePair
  • [ ] onErrorRestartLoop
• [ ] TaskLocal
• [ ] cats-effect integration
  • [ ] Timer

[Avasil]

Yeah I think it's a good idea to list everything, then do separate issues etc. It should be easier to cooperate on it. Ideally I'd see table of contents to fill. :D

Other stuff off the top of my head is cats-effect integration (related to Task and Iterant) with example (I was thinking about showing how to interoperate between Task and IO received from somewhere like http4s)

A lot of the changes can be noticed going through releases: https://monix.io/blog/2018/03/19/monix-v3.0.0-RC1.html

[alexandru]

👍

FYI our competition for Iterant has a documentation microsite now, so checking that out is useful for inspiration 😊

https://functional-streams-for-scala.github.io/fs2/

This should also give us ideas about what's missing in Monix that's important — although those aren't a priority for the 3.0.0 release, because what's there already is pretty good and we can always add stuff afterwards.

Also the Task document needs a bigger section that talks of cancelation, like I wrote for cats.effect.IO: https://typelevel.org/cats-effect/datatypes/io.html#concurrency-and-cancelation

Just one piece of advice in case you start contributing — for documentation it's better to do it piecemeal, so prefer small PRs that can be merged faster.

Incomplete documentation is better than zero documentation 🙂

[alexandru]

Btw guys, helping with the docs is extremely valuable, so thanks for taking initiative ❤️

[alexandru]

FYI, I started to work on the Iterant document.

[Avasil]

Cool, I hope to have a bit more free time after a week or two and continue Observable

[kszlim]

startAndForget would be great to document too! Didn't realize monix had something like that until I really dug through the issues/code.

[Avasil]

@kszlim I have it on my todo list so I'll get to it eventually (though I focused on Observable more) unless you want to take a shot at it