These docs were first written back when we had both a blocking and a
non-blocking API. I removed all the blocking code a long time ago, leaving on
the Twisted-based non-blocking API, but I forgot to update the docs to match,
which is why some of the text didn't make much sense.
