From 2d927cc1941cce6f320640836941ca480e958ead Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Mon, 16 Jan 2023 19:27:18 -0800 Subject: [PATCH 1/2] 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. --- library/std/src/io/error.rs | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs index 3cabf24492eaf..27aa245851617 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!")); From 0f32fd8484d3282648dc18985b7d29abad2d6b70 Mon Sep 17 00:00:00 2001 From: Jubilee Young Date: Fri, 17 Mar 2023 14:24:11 -0700 Subject: [PATCH 2/2] Remove irrelevant docs on error kinds --- library/std/src/io/error.rs | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs index 27aa245851617..6dd7859fcb40b 100644 --- a/library/std/src/io/error.rs +++ b/library/std/src/io/error.rs @@ -565,12 +565,6 @@ 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 /// /// ``` @@ -877,9 +871,9 @@ 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. + /// This may be a value set by Rust code constructing custom `io::Error`s, + /// or if this `io::Error` was sourced from the operating system, + /// it will be a value inferred from the system's error encoding. /// See [`last_os_error`] for more details. /// /// [`last_os_error`]: Error::last_os_error @@ -894,7 +888,7 @@ impl Error { /// } /// /// fn main() { - /// // As no error has occurred, this may print anything! + /// // As no error has (visibly) occurred, this may print anything! /// // It likely prints a placeholder for unidentified (non-)errors. /// print_error(Error::last_os_error()); /// // Will print "AddrInUse".