Improve documentation for core::io.
remove trailing whitespace
auto merge of #5673 : steveklabnik/rust/improve_io_docs, r=catamorphism

When I submitted #5659, it apparently caused some test failures. Then, because I left it in my incoming rather than making a new branch, I deleted my commit.

Let's try this again, this time, with its own branch so that I don't screw it up.

r?