Update Callback/Future doco

Author: japgolly

doc/CHANGELOG-0.10.md

@@ -27,10 +27,6 @@
   val f = updateComponent
   Callback.future(f)
 
-  // This is BAD because the callback wraps a single instance of updateComponent.
-  // 1) The server will be contacted immediately instead of when the callback executes.
-  // 2) If the callback is execute more than once, the future and old result will be reused.
-
   // This is GOOD too because the future is created inside the callback.
   Callback.future {
     val f = updateComponent
@@ -39,6 +35,9 @@
   }
   ```
 
+  If you're looking for ways to block (eg. turning a `Callback[Future[A]]` into a `Callback[A]`),
+  it is not supported by Scala.JS (See [#1996](https://github.com/scala-js/scala-js/issues/1996)).
+
 * Add `React.Children.toArray`.
 
 * Upgrade Scala.JS to 0.6.5.

doc/USAGE.md

@@ -13,6 +13,7 @@ It is expected that you know how React itself works.
 - [React Extensions](#react-extensions)
 - [Differences from React proper](#differences-from-react-proper)
 - [Using JS Components](#using-js-components)
+- [Callbacks and Futures](#callbacks-and-futures)
 - [Gotchas](#gotchas)
 
 Setup
@@ -586,6 +587,48 @@ mountedComponent.foreach(c =>            // GOOD: call setState
   c.setState(SampleReactComponentState(c.state)(num2 = 1)))
 ```
 
+Callbacks and Futures
+=====================
+
+There are a number of conversions available to convert between `Callback` and `Future`.
+
+| Input                      | Method                 | Output                  |
+| -------------------------- | ---------------------- | ----------------------- |
+| `CallbackTo[A]`            | `cb.toFuture`          | `Future[A]`             |
+| `CallbackTo[Future[A]]`    | `cb.toFlatFuture`      | `Future[A]`             |
+| `=> Future[A]`             | `CallbackTo(f)`        | `CallbackTo[Future[A]]` |
+| `=> Future[CallbackTo[A]]` | `Callback.future(f)`   | `Callback`              |
+| `=> Future[CallbackTo[A]]` | `CallbackTo.future(f)` | `CallbackTo[Future[A]]` |
+
+**NOTE:** It's important that when going from `Future` to `Callback`, you're aware of when the `Future` is instantiated.
+
+```scala
+def queryServer: Future[Data] = ???
+
+def updateComponent: Future[Callback] =
+  queryServer.map($ setState _)
+
+// This is GOOD because the callback wraps the updateComponent *function*, not an instance.
+Callback.future(updateComponent)
+
+// This is BAD because the callback wraps a single instance of updateComponent.
+// 1) The server will be contacted immediately instead of when the callback executes.
+// 2) If the callback is execute more than once, the future and old result will be reused.
+val f = updateComponent
+Callback.future(f)
+
+// This is GOOD too because the future is created inside the callback.
+Callback.future {
+  val f = updateComponent
+  f.onComplete(???)
+  f
+}
+```
+
+If you're looking for ways to block (eg. turning a `Callback[Future[A]]` into a `Callback[A]`),
+it is not supported by Scala.JS (See [#1996](https://github.com/scala-js/scala-js/issues/1996)).
+
+
 Gotchas
 =======