Explain the "no-error" io::Error case

Fundamentally, querying the OS for error codes is a process
that is deeply subject to the whims of chance and fortune.
We can account for OS, but not for every combination of platform APIs.
A compiled binary may not recognize new errors introduced years later.
We should clarify a few especially odd situations, and what they mean:
We can effectively promise nothing.

This allows removing mention of ErrorKind::Uncategorized.
That error variant is hidden quite deliberately, so we
should not explicitly mention it.

1 files changed, 16 insertions, 2 deletions

diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs
index 3cabf24492e..27aa2458516 100644
--- a/library/std/src/io/error.rs
+++ b/library/std/src/io/error.rs
@@ -359,7 +359,7 @@ pub enum ErrorKind {
 
     // "Unusual" error kinds which do not correspond simply to (sets
     // of) OS error codes, should be added just above this comment.
-    // `Other` and `Uncategorised` should remain at the end:
+    // `Other` and `Uncategorized` should remain at the end:
     //
     /// A custom error that does not fall under any other I/O error kind.
     ///
@@ -565,6 +565,12 @@ impl Error {
     /// other standard library functions may call platform functions that may
     /// (or may not) reset the error value even if they succeed.
     ///
+    /// If this is used in a case where no error has yet occurred in a program,
+    /// e.g. right after the beginning of `fn main`,
+    /// then in principle any possible Error may be returned.
+    /// The error code may have been set by a previous program (e.g. `execve`)
+    /// or the OS may have initialized it to an arbitrary, even random, value.
+    ///
     /// # Examples
     ///
     /// ```
@@ -871,6 +877,13 @@ impl Error {
 
     /// Returns the corresponding [`ErrorKind`] for this error.
     ///
+    /// In some cases, the ErrorKind variant may not make much sense,
+    /// either because the situation does not actually involve an error, or
+    /// because of a new error code the standard library has not been taught.
+    /// See [`last_os_error`] for more details.
+    ///
+    /// [`last_os_error`]: Error::last_os_error
+    ///
     /// # Examples
     ///
     /// ```
@@ -881,7 +894,8 @@ impl Error {
     /// }
     ///
     /// fn main() {
-    ///     // Will print "Uncategorized".
+    ///     // As no error has occurred, this may print anything!
+    ///     // It likely prints a placeholder for unidentified (non-)errors.
     ///     print_error(Error::last_os_error());
     ///     // Will print "AddrInUse".
     ///     print_error(Error::new(ErrorKind::AddrInUse, "oh no!"));