Improve documentation for core::io.

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?