Client documentation is too limited

A few aspects of this were discussed in a users forum thread, but based on initial feedback in PRs #1565 and #1568, it seems a more clear problem statement is needed.

Problem Statement

The current examples/client.rs, its guide explanation, and the client module doctest use run and no other alternatives are shown. In order to use run, these utilize futures::future::lazy to move the client into a single request future. Outwardly this makes things look minimal, clean and friendly, but as a pattern this is a dead end for building an application beyond the most trivial, single request case:

• The Client in this formulation can't be reused for more than the single request, in order to take advantage of important features like connection keep-alive.

• Methods run as used, or block_on, are inappropriate in the runtime context. Only spawn is non-blocking, but no current client example shows that usage.

• Its not obvious why lazy is needed or what the shutdown requirements of the runtime and Client are. Omitting lazy or moving the Client outside of the future can result in these examples halting (never shutting down.)

Code examples could be improved to some extent with comments. Going further, in #1565 I propose using block_on in the doctest, and in #1568: spawn and explicit shutdown in the examples/client.rs. Alternatively, instead of replacing the run + lazy examples, these could be adapted to include the alternatives along side.

Start with examples/client.rs and the client module doctest, then review the guide explanation and the feedback in PRs #1565 and #1568. Determine which client and runtime usage alternatives the documentation should present, including shutdown behavior. Done means the examples explain reuse, runtime calls, lazy, and shutdown clearly.