Splits the documentation into sections and provides an overview.
Also explicitly document which functions can and cannot be called on
 partially-open streams, and fix-up a few things to behave as
 documented.