util-core: Improve Future's scaladocs

Problem

The scaladocs for `com.twitter.util.Future` were not very thorough.

Solution

Beef up the docs with a focus on the commonly used and misused
methods.

RB_ID=542546
util-collections: add scaladoc, deprecate cruft, increase test coverage

This is a housekeeping patch that adds some tests to util-collections to increase test coverage.
Additionally I added some scaladocs, and deprecated some public interfaces that shouldn't exist.

RB_ID=528663
util-core: Add FuturePools, a Java-friendly API

RB_ID=546482