Rollup merge of rust-lang#132065 - tifv:dangling-docs, r=Noratrieb

Clarify documentation of `ptr::dangling()` function

Also fixes the safety comment in `NonNull::dangling()` function.

Fixes rust-lang#132004.

core/src/ptr/mod.rs

@@ -602,7 +602,7 @@ pub const fn without_provenance<T>(addr: usize) -> *const T {
     unsafe { mem::transmute(addr) }
 }
 
-/// Creates a new pointer that is dangling, but well-aligned.
+/// Creates a new pointer that is dangling, but non-null and well-aligned.
 ///
 /// This is useful for initializing types which lazily allocate, like
 /// `Vec::new` does.
@@ -645,7 +645,7 @@ pub const fn without_provenance_mut<T>(addr: usize) -> *mut T {
     unsafe { mem::transmute(addr) }
 }
 
-/// Creates a new pointer that is dangling, but well-aligned.
+/// Creates a new pointer that is dangling, but non-null and well-aligned.
 ///
 /// This is useful for initializing types which lazily allocate, like
 /// `Vec::new` does.

core/src/ptr/non_null.rs

@@ -107,9 +107,7 @@ impl<T: Sized> NonNull<T> {
     #[must_use]
     #[inline]
     pub const fn dangling() -> Self {
-        // SAFETY: mem::align_of() returns a non-zero usize which is then casted
-        // to a *mut T. Therefore, `ptr` is not null and the conditions for
-        // calling new_unchecked() are respected.
+        // SAFETY: ptr::dangling_mut() returns a non-null well-aligned pointer.
         unsafe {
             let ptr = crate::ptr::dangling_mut::<T>();
             NonNull::new_unchecked(ptr)