Rollup merge of #88298 - ijackson:errorkind-reorder, r=dtolnay

Errorkind reorder

I was doing a bit more work in this area and the untidiness of these two orderings bothered me.

The commit messages have the detailed rationale.  For your convenience, I c&p them here:

```
    io::ErrorKind: rationalise ordering in main enum

    It is useful to keep some coherent structure to this ordering.  In
    particular, Other and Uncategorized should be next to each other, at
    the end.

    Also it seems to make sense to treat UnexpectedEof and OutOfMemory
    specially, since they are not like the other errors (despite
    OutOfMemory also being generatable by some OS errors).

    So:
     * Move Other to the end, just before Uncategorized
     * Move Unsupported to between Interrupted and UnexpectedEof
     * Add some comments documenting where to add things
```

```
    io::Error: alphabeticise the match in as_str()

    There was no rationale for the previous ordering.
```

r? kennytm   since that's who rust-highfive picked before, in #88294 which I accidentally closed.

library/std/src/io/error.rs

@@ -261,6 +261,33 @@ pub enum ErrorKind {
     #[stable(feature = "rust1", since = "1.0.0")]
     Interrupted,
 
+    /// This operation is unsupported on this platform.
+    ///
+    /// This means that the operation can never succeed.
+    #[stable(feature = "unsupported_error", since = "1.53.0")]
+    Unsupported,
+
+    // ErrorKinds which are primarily categorisations for OS error
+    // codes should be added above.
+    //
+    /// An error returned when an operation could not be completed because an
+    /// "end of file" was reached prematurely.
+    ///
+    /// This typically means that an operation could only succeed if it read a
+    /// particular number of bytes but only a smaller number of bytes could be
+    /// read.
+    #[stable(feature = "read_exact", since = "1.6.0")]
+    UnexpectedEof,
+
+    /// An operation could not be completed, because it failed
+    /// to allocate enough memory.
+    #[stable(feature = "out_of_memory_error", since = "1.54.0")]
+    OutOfMemory,
+
+    // "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:
+    //
     /// A custom error that does not fall under any other I/O error kind.
     ///
     /// This can be used to construct your own [`Error`]s that do not match any
@@ -274,26 +301,6 @@ pub enum ErrorKind {
     #[stable(feature = "rust1", since = "1.0.0")]
     Other,
 
-    /// An error returned when an operation could not be completed because an
-    /// "end of file" was reached prematurely.
-    ///
-    /// This typically means that an operation could only succeed if it read a
-    /// particular number of bytes but only a smaller number of bytes could be
-    /// read.
-    #[stable(feature = "read_exact", since = "1.6.0")]
-    UnexpectedEof,
-
-    /// This operation is unsupported on this platform.
-    ///
-    /// This means that the operation can never succeed.
-    #[stable(feature = "unsupported_error", since = "1.53.0")]
-    Unsupported,
-
-    /// An operation could not be completed, because it failed
-    /// to allocate enough memory.
-    #[stable(feature = "out_of_memory_error", since = "1.54.0")]
-    OutOfMemory,
-
     /// Any I/O error from the standard library that's not part of this list.
     ///
     /// Errors that are `Uncategorized` now may move to a different or a new
@@ -307,13 +314,13 @@ pub enum ErrorKind {
 impl ErrorKind {
     pub(crate) fn as_str(&self) -> &'static str {
         use ErrorKind::*;
+        // Strictly alphabetical, please.  (Sadly rustfmt cannot do this yet.)
         match *self {
             AddrInUse => "address in use",
             AddrNotAvailable => "address not available",
             AlreadyExists => "entity already exists",
             ArgumentListTooLong => "argument list too long",
             BrokenPipe => "broken pipe",
-            ResourceBusy => "resource busy",
             ConnectionAborted => "connection aborted",
             ConnectionRefused => "connection refused",
             ConnectionReset => "connection reset",
@@ -321,9 +328,10 @@ impl ErrorKind {
             Deadlock => "deadlock",
             DirectoryNotEmpty => "directory not empty",
             ExecutableFileBusy => "executable file busy",
-            FilenameTooLong => "filename too long",
-            FilesystemQuotaExceeded => "filesystem quota exceeded",
             FileTooLarge => "file too large",
+            FilenameTooLong => "filename too long",
+            FilesystemLoop => "filesystem loop or indirection limit (e.g. symlink loop)",
+            FilesystemQuotaExceeded => "filesystem quota exceeded",
             HostUnreachable => "host unreachable",
             Interrupted => "operation interrupted",
             InvalidData => "invalid data",
@@ -332,16 +340,16 @@ impl ErrorKind {
             NetworkDown => "network down",
             NetworkUnreachable => "network unreachable",
             NotADirectory => "not a directory",
-            StorageFull => "no storage space",
             NotConnected => "not connected",
             NotFound => "entity not found",
+            NotSeekable => "seek on unseekable file",
             Other => "other error",
             OutOfMemory => "out of memory",
             PermissionDenied => "permission denied",
             ReadOnlyFilesystem => "read-only filesystem or storage medium",
+            ResourceBusy => "resource busy",
             StaleNetworkFileHandle => "stale network file handle",
-            FilesystemLoop => "filesystem loop or indirection limit (e.g. symlink loop)",
+            StorageFull => "no storage space",
-            NotSeekable => "seek on unseekable file",
             TimedOut => "timed out",
             TooManyLinks => "too many links",
             Uncategorized => "uncategorized error",