From f950edbef773c101bf1ed79fb82e3704e1fb9ebc Mon Sep 17 00:00:00 2001
From: Thom Chiovoloni <chiovolonit@gmail.com>
Date: Fri, 29 Oct 2021 19:35:09 -0700
Subject: [PATCH] Elaborate some in the documentation and respond to some
 review comments

---
 library/std/src/io/error.rs                |  1 -
 library/std/src/io/error/repr_bitpacked.rs | 26 ++++++++++++++++------
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs
index 8f82778e90b..5f0a8a72c02 100644
--- a/library/std/src/io/error.rs
+++ b/library/std/src/io/error.rs
@@ -88,7 +88,6 @@ enum ErrorData<C> {
 // requires an alignment >= 4 (note that `#[repr(align)]` will not reduce the
 // alignment required by the struct, only increase it).
 #[repr(align(4))]
-#[doc(hidden)]
 pub(crate) struct SimpleMessage {
     kind: ErrorKind,
     message: &'static str,
diff --git a/library/std/src/io/error/repr_bitpacked.rs b/library/std/src/io/error/repr_bitpacked.rs
index 9b7c34f67a0..dbe6c34d547 100644
--- a/library/std/src/io/error/repr_bitpacked.rs
+++ b/library/std/src/io/error/repr_bitpacked.rs
@@ -2,17 +2,29 @@
 //! 64-bit pointers.
 //!
 //! (Note that `bitpacked` vs `unpacked` here has no relationship to
-//! `#[repr(packed)]`, it just refers to attempting to use any available
-//! bits in a more clever manner than `rustc`'s default layout algorithm would).
+//! `#[repr(packed)]`, it just refers to attempting to use any available bits in
+//! a more clever manner than `rustc`'s default layout algorithm would).
 //!
-//! Conceptually, it stores the same information as the "unpacked" equivalent we
-//! use on other targets: `repr_unpacked::Repr` (see repr_unpacked.rs), however
-//! it packs it into a 64bit non-zero value.
+//! Conceptually, it stores the same data as the "unpacked" equivalent we use on
+//! other targets. Specifically, you can imagine it as an optimized following
+//! data (which is equivalent to what's stored by `repr_unpacked::Repr`, e.g.
+//! `super::ErrorData<Box<Custom>>`):
+//!
+//! ```ignore (exposition-only)
+//! enum ErrorData {
+//!    Os(i32),
+//!    Simple(ErrorKind),
+//!    SimpleMessage(&'static SimpleMessage),
+//!    Custom(Box<Custom>),
+//! }
+//! ```
+//!
+//! However, it packs this data into a 64bit non-zero value.
 //!
 //! This optimization not only allows `io::Error` to occupy a single pointer,
 //! but improves `io::Result` as well, especially for situations like
-//! `Result<()>` (which is now 64 bits) or `Result<u64>` (which i), which are
-//! quite common.
+//! `io::Result<()>` (which is now 64 bits) or `io::Result<u64>` (which is now
+//! 128 bits), which are quite common.
 //!
 //! # Layout
 //! Tagged values are 64 bits, with the 2 least significant bits used for the