Improve documentation of std.io.ErrorKind variants

[Havvy]

On the std.io.ErrorKind documentation page, there's a list of error kinds along with descriptions of what the kinds mean.

I personally got confused by what the new variant InvalidData actually means from that description. How do I have operation parameters but "malformed" data? What even is a parameter in this case? I know a parameter as an input to a function, but Rust is supposed to typecheck my problems, so how do they happen? Is it because of raw pointer stuff perchance? I don't really know from looking at that documentation, and I'm hopelessly confused.

But because I'm hopelessly confused, I thought I'd look for a link to some usage of these kinds - learn by example. But there's no linking to functions that might return these variants specifically that I can go to and read their documentation. I think these links would be invaluable for what is probably going to be the most read error page in the standard library documentation.

[eefriedman]

A quick search of the source code shows that it's generally used for input with an invalid encoding, e.g. when you use read_line() with a file that doesn't contain valid UTF-8. Granted, the description could be better.

[nathankleyn]

I thought about tackling this as a nice easy doc change and a foray into contributing, but when I saw the usages of InvalidInput and InvalidData there really isn't definitive differentiation to go on.

I did a code-search on GitHub for usages of the two:

• Here's the usages of InvalidInput.
• Here's the usages of InvalidData.

They both appear to be used almost identically, in that people are using both to represent corrupted or malformed parameter data. My gut feeling says InvalidData was meant to be the error type for this job (parameter values), and that InvalidInput was meant for returning errors related to parameter types across program boundaries (eg. arguments to external programs, shell calls, etc). Not sure who would know, but would be good to get some confirmation of what these were supposed to mean.

[nathankleyn]

cc/ @steveklabnik Not sure if you can shed some light on what these are meant to be.

[steveklabnik]

I am not sure what the difference is either, @rust-lang/libs , any ideas?

[alexcrichton]

InvalidData is intended to be used where no I/O errors happened but the data was malformed (e.g. not UTF-8 or not UTF-16 or something like that). It was added fairly recently.

The InvalidInput variant is otherwise just used in places for "invalid state". I agree the distinction here is odd.