std::io functions should document which ErrorKinds they can return

[durka]

See this reddit post where the question was "How can File::open fail?" and the information is sort of there in the docs, but I was reduced to guessing io::ErrorKind variants from the text description of errors. Similar to how Unix man pages list exactly which errno values are possible, the std::io functions should list the exact variants they might return.

[retep998]

More specifically it should document which system error codes correspond to which ErrorKind.

[durka]

I guess so, but that's system-dependent. We can say that File::open fails with NotFound even if that is a different code on Windows vs Linux or whatever.

[nagisa]

even if that is a different code on Windows vs Linux or whatever.

I do not think it is in our interest to maintain descriptions of every possible failure. We already document what platform API some call corresponds to, so referring people to corresponding documentation seems entirely fine to me

[durka]

I don't know about our interest, but it seems to be in the users' interest to avoid a round trip to system manpages.

…

On Wed, Mar 8, 2017 at 7:11 AM, Simonas Kazlauskas ***@***.*** > wrote: even if that is a different code on Windows vs Linux or whatever. I do not think it is in our interest to maintain descriptions of every possible failure. We already document what platform API some call corresponds to, so referring people to corresponding documentation seems entirely fine to me — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#40322 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC3n6b4y74e7DiYn8Dxcbaho9M24BLTks5rjprsgaJpZM4MVrhb> .

[durka]

Also I don't see where OpenOptions::open specifies a system call (I feel like I'm nitpicking, since it's obviously(?) `open` on Linux, but I don't know what it is on Windows).

…

On Wed, Mar 8, 2017 at 9:52 AM, Alex Burka ***@***.***> wrote: I don't know about our interest, but it seems to be in the users' interest to avoid a round trip to system manpages. On Wed, Mar 8, 2017 at 7:11 AM, Simonas Kazlauskas < ***@***.***> wrote: > even if that is a different code on Windows vs Linux or whatever. > > I do not think it is in our interest to maintain descriptions of every > possible failure. We already document what platform API some call > corresponds to, so referring people to corresponding documentation seems > entirely fine to me > > — > You are receiving this because you authored the thread. > Reply to this email directly, view it on GitHub > <#40322 (comment)>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/AAC3n6b4y74e7DiYn8Dxcbaho9M24BLTks5rjprsgaJpZM4MVrhb> > . >

[steveklabnik]

triage: p-medium. putting it on the next doc team agenda

[steveklabnik]

Docs team discussed this today. What we plan to do is basically what the original post says; but we want to make sure that we do it in a way that suggests common errors rather than hard-specifying that it can only return one of them. The practical consideration is that the "common" errors will not be the exhaustive list, but that doesn't paint anyone into a corner later.