Fixes to ConnectionPool noticed during upstream review

Suggested by Jake Wharton. Minor documentation fixes, plus:

The pool should explicitly re-enter DRAINING state if a
connection is added to a drained pool. This state change was
missing.

The pool was implicitly in DRAINING while the pool still had
connections in it, so the pool would still drain.
However, adding back connections to a pool that was DRAINING
but still incorrectly marked as DRAINED would cause a
new runnable to be scheduled. This would cause the queue of
scheduled items to grow unnecesarily and the clean up thread
would continue to operate longer than necessary.

Bug: 18369687
(cherry picked from commit 6257f0c1)

Change-Id: Id60486a70163679d4f587ea75b71fc438a1d8df0