Rollup merge of #72277 - RalfJung:manually-drop-docs, r=Mark-Simulacrum

emphasize that ManuallyDrop is safe-to-access and unsafe-to-drop

This seems to sometimes confused people, and generally seems reasonable to state in the top-level summary of the type.

1 files changed, 5 insertions, 1 deletions

diff --git a/src/libcore/mem/manually_drop.rs b/src/libcore/mem/manually_drop.rs
index 17863dd38af..18767c482c7 100644
--- a/src/libcore/mem/manually_drop.rs
+++ b/src/libcore/mem/manually_drop.rs
@@ -2,7 +2,6 @@ use crate::ops::{Deref, DerefMut};
 use crate::ptr;
 
 /// 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`.
@@ -11,6 +10,11 @@ use crate::ptr;
 /// with [`mem::zeroed`] is undefined behavior.
 /// If you need to handle uninitialized data, use [`MaybeUninit<T>`] instead.
 ///
+/// Note that accessing the value inside a `ManuallyDrop<T>` is safe.
+/// This means that a `ManuallyDrop<T>` whose content has been dropped must not
+/// be exposed through a public safe API.
+/// Correspondingly, `ManuallyDrop::drop` is unsafe.
+///
 /// # Examples
 ///
 /// This wrapper can be used to enforce a particular drop order on fields, regardless