reference NonNull::dangling

2 files changed, 12 insertions, 9 deletions

diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs
index 7fd91aba321..9676572e45d 100644
--- a/library/alloc/src/boxed.rs
+++ b/library/alloc/src/boxed.rs
@@ -62,10 +62,12 @@
 //! T` obtained from [`Box::<T>::into_raw`] may be deallocated using the
 //! [`Global`] allocator with [`Layout::for_value(&*value)`].
 //!
-//! For zero-sized values, the `Box` pointer still has to be [valid] for reads and writes and
-//! sufficiently aligned. In particular, casting any aligned non-zero integer literal to a raw
-//! pointer produces a valid pointer, but a pointer pointing into previously allocated memory that
-//! since got freed is not valid.
+//! For zero-sized values, the `Box` pointer still has to be [valid] for reads
+//! and writes and sufficiently aligned. In particular, casting any aligned
+//! non-zero integer literal to a raw pointer produces a valid pointer, but a
+//! pointer pointing into previously allocated memory that since got freed is
+//! not valid. The recommended way to build a Box to a ZST if `Box::new` cannot
+//! be used is to use [`ptr::NonNull::dangling`].
 //!
 //! So long as `T: Sized`, a `Box<T>` is guaranteed to be represented
 //! as a single pointer and is also ABI-compatible with C pointers
diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs
index 243346a429a..6544dd4fd7a 100644
--- a/library/core/src/ptr/mod.rs
+++ b/library/core/src/ptr/mod.rs
@@ -20,11 +20,12 @@
 //!   be *dereferenceable*: the memory range of the given size starting at the pointer must all be
 //!   within the bounds of a single allocated object. Note that in Rust,
 //!   every (stack-allocated) variable is considered a separate allocated object.
-//! * Even for operations of [size zero][zst], the pointer must not be "dangling" in the sense of
-//!   pointing to deallocated memory. However, casting any non-zero integer literal to a pointer is
-//!   valid for zero-sized accesses. This corresponds to writing your own allocator; allocating
-//!   zero-sized objects is not very hard. In contrast, when you use the standard allocator, after
-//!   memory got deallocated, even zero-sized accesses to that memory are invalid.
+//! * Even for operations of [size zero][zst], the pointer must not be pointing to deallocated
+//!   memory, i.e., deallocation makes pointers invalid even for zero-sized operations. However,
+//!   casting any non-zero integer *literal* to a pointer is valid for zero-sized accesses, even if
+//!   some memory happens to exist at that address and gets deallocated. This corresponds to writing
+//!   your own allocator: allocating zero-sized objects is not very hard. The canonical way to
+//!   obtain a pointer that is valid for zero-sized accesses is [`NonNull::dangling`].
 //! * All accesses performed by functions in this module are *non-atomic* in the sense
 //!   of [atomic operations] used to synchronize between threads. This means it is
 //!   undefined behavior to perform two concurrent accesses to the same location from different