From f5118a525fcf9db4102d903650331039158eff11 Mon Sep 17 00:00:00 2001
From: Laurence Tratt <laurie@tratt.net>
Date: Wed, 12 Aug 2020 15:36:55 +0100
Subject: [PATCH] Clarify and add guarantee about `transmute`.

---
 library/core/src/option.rs | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index 745b0f1ae8d47..c1837f79840d5 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -72,16 +72,19 @@
 //!
 //! # Representation
 //!
-//! Rust guarantees to optimise the following inner types such that an [`Option`] which contains
-//! them has the same size as a pointer:
+//! Rust guarantees to optimize the following types `<T>` such that an
+//! [`Option<T>`] has the same size as `T`:
 //!
+//! * [`Box<T>`]
 //! * `&T`
 //! * `&mut T`
 //! * `extern "C" fn`
 //! * [`num::NonZero*`]
 //! * [`ptr::NonNull<T>`]
 //! * `#[repr(transparent)]` struct around one of the types in this list.
-//! * [`Box<T>`]
+//!
+//! For the above cases, it is guaranteed that one can use [`mem::transmute`]
+//! between `T` and `Option<T>` and vice versa.
 //!
 //! # Examples
 //!