Touch up documentation about futures (#1753)

guide/src/reference/js-promises-and-rust-futures.md

@@ -13,3 +13,12 @@ Learn more:
 
 [crate]: https://crates.io/crates/wasm-bindgen-futures
 [docs]: https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen_futures/
+
+## Compatibility with versions of `Future`
+
+The current crate on crates.io, `wasm-bindgen-futures 0.4.*`, supports
+`std::future::Future` and `async`/`await` in Rust. This typically requires Rust
+1.39.0+ (as of this writing on 2019-09-05 it's the nightly channel of Rust).
+
+If you're using the `Future` trait from the `futures` `0.1.*` crate then you'll
+want to use the `0.3.*` track of `wasm-bindgen-futures` on crates.io.

guide/src/wasm-bindgen-test/asynchronous-tests.md

@@ -5,37 +5,34 @@ like fetching resources and/or other bits and pieces. To accommodate this
 asynchronous tests are also supported through the `futures` and
 `wasm-bindgen-futures` crates.
 
-To write an asynchronous test:
-
-1. Change `#[wasm_bindgen_test]` into `#[wasm_bindgen_test(async)]`
-
-2. Change the return type of the test function to `impl Future<Item = (), Error
-   = JsValue>`
-
-The test will pass if the future resolves without panicking or returning an
-error, and otherwise the test will fail.
-
-## Example
+Writing an asynchronous test is pretty simple, just use an `async` function!
+You'll also likely want to use the `wasm-bindgen-futures` crate to convert JS
+promises to Rust futures.
 
 ```rust
-extern crate futures;
-extern crate js_sys;
-extern crate wasm_bindgen_futures;
-
-use futures::Future;
 use wasm_bindgen::prelude::*;
 use wasm_bindgen_futures::JsFuture;
 
-#[wasm_bindgen_test(async)]
-fn my_async_test() -> impl Future<Item = (), Error = JsValue> {
+#[wasm_bindgen_test]
+async fn my_async_test() {
     // Create a promise that is ready on the next tick of the micro task queue.
     let promise = js_sys::Promise::resolve(&JsValue::from(42));
 
     // Convert that promise into a future and make the test wait on it.
-    JsFuture::from(promise)
-        .map(|x| {
-            assert_eq!(x, 42);
-        })
-        .map_err(|_| unreachable!())
+    let x = JsFuture::from(promise).await.unwrap();:
+    assert_eq!(x, 42);
 }
 ```
+
+## Rust compiler compatibility
+
+Note that `async` functions are only supported in stable from Rust 1.39.0 and
+beyond. As of the time of this writing (2019-09-05) this is the Nightly channel
+of Rust.
+
+If you're using the `futures` crate from crates.io in its 0.1 version then
+you'll want to use the `0.3.*` version of `wasm-bindgen-futures` and the `0.2.8`
+version of `wasm-bindgen-test`. In those modes you'll also need to use
+`#[wasm_bindgen_test(async)]` instead of using an `async` function. In general
+we'd recommend using the nightly version with `async` since the user experience
+is much improved!

guide/src/wasm-bindgen-test/usage.md

@@ -2,14 +2,15 @@
 
 ### Add `wasm-bindgen-test` to Your `Cargo.toml`'s `[dev-dependencies]`
 
-Make sure to replace "X.Y.Z" with the same version of `wasm-bindgen` that you
-have in the `[dependencies]` section!
-
 ```toml
 [dev-dependencies]
-wasm-bindgen-test = "X.Y.Z"
+wasm-bindgen-test = "0.3.0"
 ```
 
+Note that the `0.3.0` track of `wasm-bindgen-test` supports Rust 1.39.0+, which
+is currently the nightly channel (as of 2019-09-05). If you want support for
+older compilers use the `0.2.*` track of `wasm-bindgen-test`.
+
 ## Write Some Tests
 
 Create a `$MY_CRATE/tests/wasm.rs` file: