ManuallyDrop != MaybeUninit

diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs
index f41d293e80ad3da86b45c6a069734d50eff5a892..6b1b91d00faa7534d38af58c8956c361a73bbf19 100644 (file)
--- a/src/libcore/mem.rs
+++ b/src/libcore/mem.rs
@@ -900,10 +900,16 @@ pub fn discriminant<T>(v: &T) -> Discriminant<T> {
     }
 }
 
+// FIXME: Reference `MaybeUninit` from these docs, once that is stable.
 /// A wrapper to inhibit compiler from automatically calling `T`’s destructor.
 ///
 /// This wrapper is 0-cost.
 ///
+/// `ManuallyDrop<T>` is subject to the same layout optimizations as `T`.
+/// As a consequence, it has *no effect* on the assumptions that the compiler makes
+/// about all values being initialized at their type.  In particular, initializing
+/// a `ManuallyDrop<&T>` with [`mem::zeroed`] is undefined behavior.
+///
 /// # Examples
 ///
 /// This wrapper helps with explicitly documenting the drop order dependencies between fields of
@@ -935,6 +941,8 @@ pub fn discriminant<T>(v: &T) -> Discriminant<T> {
 ///     }
 /// }
 /// ```
+///
+/// [`mem::zeroed']: fn.zeroed.html
 #[stable(feature = "manually_drop", since = "1.20.0")]
 #[lang = "manually_drop"]
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]