From 2d927cc1941cce6f320640836941ca480e958ead Mon Sep 17 00:00:00 2001
From: Jubilee Young <workingjubilee@gmail.com>
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 <workingjubilee@gmail.com>
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".