Merge pull request #153 from alexandru/docs10

Update IO's document

.gitignore

@@ -8,3 +8,4 @@ tags
 .idea
 benchmarks/results
 .java-version
+.DS_Store

README.md

@@ -4,7 +4,7 @@
 
 > For when purity just isn't impure enough.
 
-This project aims to provide a standard [`IO`](https://oss.sonatype.org/service/local/repositories/releases/archive/org/typelevel/cats-effect_2.12/0.5/cats-effect_2.12-0.5-javadoc.jar/!/cats/effect/IO.html) type for the [cats](http://typelevel.org/cats/) ecosystem, as well as a set of typeclasses (and associated laws!) which characterize general effect types.  This project was *explicitly* designed with the constraints of the JVM and of JavaScript in mind.  Critically, this means two things:
+This project aims to provide a standard [`IO`](https://oss.sonatype.org/service/local/repositories/releases/archive/org/typelevel/cats-effect_2.12/0.10/cats-effect_2.12-0.10-javadoc.jar/!/cats/effect/IO.html) type for the [cats](http://typelevel.org/cats/) ecosystem, as well as a set of typeclasses (and associated laws!) which characterize general effect types.  This project was *explicitly* designed with the constraints of the JVM and of JavaScript in mind.  Critically, this means two things:
 
 - Manages both synchronous *and* asynchronous (callback-driven) effects
 - Compatible with a single-threaded runtime
@@ -13,10 +13,10 @@ In this way, `IO` is more similar to common `Task` implementations than it is to
 
 ## Usage
 
-The most current stable release of cats-effect is **0.9**.  We are confident in the quality of this release, and do consider it "production-ready".  However, we will not be *guaranteeing* source compatibility until the 1.0 release, which will depend on cats-core 1.0 (when it is released).  See [compatibility and versioning](https://github.com/typelevel/cats-effect/blob/master/versioning.md) for more information on our compatibility and semantic versioning policies.
+The most current stable release of cats-effect is **0.10**.  We are confident in the quality of this release, and do consider it "production-ready".  However, we will not be *guaranteeing* source compatibility until the 1.0 release, which will depend on cats-core 1.0 (when it is released).  See [compatibility and versioning](https://github.com/typelevel/cats-effect/blob/master/versioning.md) for more information on our compatibility and semantic versioning policies.
 
 ```sbt
-libraryDependencies += "org.typelevel" %% "cats-effect" % "0.9"
+libraryDependencies += "org.typelevel" %% "cats-effect" % "0.10"
 ```
 
 If your project uses Scala.js, replace the double-`%` with a triple.  Note that **cats-effect** has an upstream dependency on **cats-core** version 1.0.1.
@@ -32,7 +32,7 @@ Please see [this document](https://github.com/typelevel/cats-effect/blob/master/
 The **cats-effect-laws** artifact provides [Discipline-style](https://github.com/typelevel/discipline) laws for the `Sync`, `Async`, `Concurrent`, `Effect` and `ConcurrentEffect` typeclasses (`LiftIO` is lawless, but highly parametric).  It is relatively easy to use these laws to test your own implementations of these typeclasses. Take a look [here](https://github.com/typelevel/cats-effect/tree/master/laws/shared/src/main/scala/cats/effect/laws) for more.
 
 ```sbt
-libraryDependencies += "org.typelevel" %% "cats-effect-laws" % "0.9" % "test"
+libraryDependencies += "org.typelevel" %% "cats-effect-laws" % "0.10" % "test"
 ```
 
 These laws are compatible with both Specs2 and ScalaTest.

build.sbt

@@ -348,9 +348,9 @@ lazy val siteSettings = Seq(
     micrositeFooterText := None,
     micrositeHighlightTheme := "atom-one-light",
     micrositePalette := Map(
-      "brand-primary" -> "#5B5988",
-      "brand-secondary" -> "#292E53",
-      "brand-tertiary" -> "#222749",
+      "brand-primary" -> "#3e5b95",
+      "brand-secondary" -> "#294066",
+      "brand-tertiary" -> "#2d5799",
       "gray-dark" -> "#49494B",
       "gray" -> "#7B7B7E",
       "gray-light" -> "#E5E5E6",

core/shared/src/main/scala/cats/effect/IO.scala

@@ -32,12 +32,26 @@ import scala.util.{Failure, Left, Right, Success}
  * side effect, where the result of that side effect may be obtained
  * synchronously (via return) or asynchronously (via callback).
  *
- * Effects contained within this abstraction are not evaluated until
+ * `IO` values are pure, immutable values and thus preserve
+ * referential transparency, being usable in functional programming.
+ * An `IO` is a data structure that represents just a description
+ * of a side effectful computation.
+ *
+ * `IO` can describe synchronous or asynchronous computations that:
+ *
+ *  1. on evaluation yield exactly one result
+ *  1. can end in either success or failure and in case of failure
+ *     `flatMap` chains get short-circuited (`IO` implementing
+ *     the algebra of `MonadError`)
+ *  1. can be canceled, but note this capability relies on the
+ *     user to provide cancelation logic
+ *
+ * Effects described via this abstraction are not evaluated until
  * the "end of the world", which is to say, when one of the "unsafe"
- * methods are used.  Effectful results are not memoized, meaning that
+ * methods are used. Effectful results are not memoized, meaning that
  * memory overhead is minimal (and no leaks), and also that a single
  * effect may be run multiple times in a referentially-transparent
- * manner.  For example:
+ * manner. For example:
  *
  * {{{
  * val ioa = IO { println("hey!") }
@@ -53,30 +67,19 @@ import scala.util.{Failure, Left, Right, Success}
  * The above will print "hey!" twice, as the effect will be re-run
  * each time it is sequenced in the monadic chain.
  *
- * `IO` is trampolined for all ''synchronous'' joins.  This means that
+ * `IO` is trampolined in its `flatMap` evaluation. This means that
  * you can safely call `flatMap` in a recursive function of arbitrary
- * depth, without fear of blowing the stack.  However, `IO` cannot
- * guarantee stack-safety in the presence of arbitrarily nested
- * asynchronous suspensions.  This is quite simply because it is
- * ''impossible'' (on the JVM) to guarantee stack-safety in that case.
- * For example:
+ * depth, without fear of blowing the stack.
  *
  * {{{
- * def lie[A]: IO[A] = IO.async(cb => cb(Right(lie))).flatMap(a => a)
+ *   def fib(n: Int, a: Long = 0, b: Long = 1): IO[Long] =
+ *     IO(a + b).flatMap { b2 =>
+ *       if (n > 0)
+ *         fib(n - 1, b, b2)
+ *       else
+ *         IO.pure(b2)
+ *     }
  * }}}
- *
- * This should blow the stack when evaluated. Also note that there is
- * no way to encode this using `tailRecM` in such a way that it does
- * ''not'' blow the stack.  Thus, the `tailRecM` on `Monad[IO]` is not
- * guaranteed to produce an `IO` which is stack-safe when run, but
- * will rather make every attempt to do so barring pathological
- * structure.
- *
- * `IO` makes no attempt to control finalization or guaranteed
- * resource-safety in the presence of concurrent preemption, simply
- * because `IO` does not care about concurrent preemption at all!
- * `IO` actions are not interruptible and should be considered
- * broadly-speaking atomic, at least when used purely.
  */
 sealed abstract class IO[+A] extends internals.IOBinaryCompat[A] {
   import IO._

site/src/main/resources/microsite/js/toc.js

@@ -103,7 +103,7 @@ document.addEventListener('DOMContentLoaded', function () {
 
     $('#toc').toc({
       title: '',
-      headers: 'h2, h3',
+      headers: 'h2, h3, h4',
       listType: 'ul',
       showSpeed: 0,
       classes: {