[docs] the spawn_future method needs documentation

[nikomatsakis]

The Scope::spawn_future() method is currently undocumented and needs /// foo documentation. The documentation should probably be fairly similar to Scope::spawn(), but there are some things to note:

• When a future is spawned, it will begin to execute asynchronously to compute its result. You get back another future (of type RayonFuture) that can be used to access that result.
• If you drop this new future, this is considered to be an indication that you no longer care about the result, and hence your original code may not execute. Put another way, spawn_future() is intended for computing values asynchronously, and not for side-effecting tasks. spawn() is better if you have side-effects you wish to observe.
• The best way to use the value that results from the future is typically to create a new future, e.g. with Future::and_then(). However, you may also invoke RayonFuture::rayon_wait() on the returned future, which will block for the value. Invoking Future::wait() from inside a Rayon thread may cause deadlocks or panics and is not recommended.

[lilianmoraru]

Some usage examples would also be helpful.
I wanted to use tokio-io and combine them with Rayon's new features support(I want to dispatch heavier tasks on the content read from files) but it's not very clear how Rayon plays the role in the ecosystem(I am sure one can get a grip while playing with these 2, but code examples would help here).

[nikomatsakis]

@lilianmoraru yes. I'd like to know the answer too. =P I've been refactoring the support for futures in rayon anyhow (rather slowly), once that's done I'll try to write-up some docs.

[nikomatsakis]

Removing from the milestone since this is not part of the 1.0 API.

[abonander]

@nikomatsakis is rayon-futures abandoned, or is it waiting for the futures stuff to stabilize? It's a bit confusing because the docs for spawn() refer to spawn_future() but that doesn't currently exist in the crate's API.

[gakonst]

Bump, is there any chance we can get this feature back again? Currently using crossbeam's spawn, save the JoinHandle and call join on it as an alternative.

[cuviper]

As of #715 and #716, yes rayon-futures is abandoned -- that doc reference needs to be removed. We have thought a bit about bringing that functionality directly to rayon-core in some form, like #679, but it's not clear what that should look like.