Change io_error abstraction

[nickdesaulniers]

Looking at the example for handling io_errors leaves a bad taste in my mouth. Not that I have any [helpful] suggestions, but can we simplify the APIs around IO and error handling?

[nickdesaulniers]

Even the docs for read are kind of a mess.

[alexcrichton]

You may be interested in #11946, we're switching to Result everywhere instead of a condition.