Rollup merge of rust-lang#52508 - joshtriplett:dangling-not-sentinel, r=Mark-Simulacrum

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.

Author: kennytm

src/libcore/ptr.rs

@@ -2716,6 +2716,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 {
@@ -2847,6 +2852,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 {