Explicitly document the size guarantees that Option makes.

Triggered by a discussion on wg-unsafe-code-guidelines about which layouts of
`Option<T>` one can guarantee are optimised to a single pointer.

1 files changed, 12 insertions, 4 deletions

diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index 3c7211fe040..745b0f1ae8d 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -70,10 +70,18 @@
 //! }
 //! ```
 //!
-//! This usage of [`Option`] to create safe nullable pointers is so
-//! common that Rust does special optimizations to make the
-//! representation of [`Option`]`<`[`Box<T>`]`>` a single pointer. Optional pointers
-//! in Rust are stored as efficiently as any other pointer type.
+//! # Representation
+//!
+//! Rust guarantees to optimise the following inner types such that an [`Option`] which contains
+//! them has the same size as a pointer:
+//!
+//! * `&T`
+//! * `&mut T`
+//! * `extern "C" fn`
+//! * [`num::NonZero*`]
+//! * [`ptr::NonNull<T>`]
+//! * `#[repr(transparent)]` struct around one of the types in this list.
+//! * [`Box<T>`]
 //!
 //! # Examples
 //!