Document that Unique::empty() and NonNull::dangling() aren't sentinel values

The documentation of Unique::empty() and NonNull::dangling() could
potentially suggest that they work as sentinel values indicating a
not-yet-initialized pointer. However, they both declare a non-null
pointer equal to the alignment of the type, which could potentially
reference a valid value of that type (specifically, the first such valid
value in memory). Explicitly document that the return value of these
functions does not work as a sentinel value.

1 files changed, 10 insertions, 0 deletions

diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index 0af642258c2..d8e061496d9 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -2703,6 +2703,11 @@ impl<T: Sized> Unique<T> {
     ///
     /// This is useful for initializing types which lazily allocate, like
     /// `Vec::new` does.
+    ///
+    /// Note that the pointer value may potentially represent a valid pointer to
+    /// a `T`, which means this must not be used as a "not yet initialized"
+    /// sentinel value. Types that lazily allocate must track initialization by
+    /// some other means.
     // FIXME: rename to dangling() to match NonNull?
     pub const fn empty() -> Self {
         unsafe {
@@ -2834,6 +2839,11 @@ impl<T: Sized> NonNull<T> {
     ///
     /// This is useful for initializing types which lazily allocate, like
     /// `Vec::new` does.
+    ///
+    /// Note that the pointer value may potentially represent a valid pointer to
+    /// a `T`, which means this must not be used as a "not yet initialized"
+    /// sentinel value. Types that lazily allocate must track initialization by
+    /// some other means.
     #[stable(feature = "nonnull", since = "1.25.0")]
     pub fn dangling() -> Self {
         unsafe {