Elaborate some in the documentation and respond to some review comments

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,

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
+//! `#[repr(packed)]`, it just refers to attempting to use any available bits in
-//! bits in a more clever manner than `rustc`'s default layout algorithm would).
+//! a more clever manner than `rustc`'s default layout algorithm would).
 //!
-//! Conceptually, it stores the same information as the "unpacked" equivalent we
+//! Conceptually, it stores the same data as the "unpacked" equivalent we use on
-//! use on other targets: `repr_unpacked::Repr` (see repr_unpacked.rs), however
+//! other targets. Specifically, you can imagine it as an optimized following
-//! it packs it into a 64bit non-zero value.
+//! 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
+//! `io::Result<()>` (which is now 64 bits) or `io::Result<u64>` (which is now
-//! quite common.
+//! 128 bits), which are quite common.
 //!
 //! # Layout
 //! Tagged values are 64 bits, with the 2 least significant bits used for the