rust-lang#66219 documented unsafe in core::ptr

Author: foeb

src/libcore/ptr/mod.rs

@@ -65,8 +65,6 @@
 //! [`write_volatile`]: ./fn.write_volatile.html
 //! [`NonNull::dangling`]: ./struct.NonNull.html#method.dangling
 
-// ignore-tidy-undocumented-unsafe
-
 #![stable(feature = "rust1", since = "1.0.0")]
 
 use crate::intrinsics;
@@ -251,6 +249,7 @@ pub(crate) struct FatPtr<T> {
 #[inline]
 #[unstable(feature = "slice_from_raw_parts", reason = "recently added", issue = "36925")]
 pub fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T] {
+    // SAFETY: FatPtr.data and Repr.rust are both usize in the same location
     unsafe { Repr { raw: FatPtr { data, len } }.rust }
 }
 
@@ -267,6 +266,7 @@ pub fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T] {
 #[inline]
 #[unstable(feature = "slice_from_raw_parts", reason = "recently added", issue = "36925")]
 pub fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T] {
+    // SAFETY: FatPtr.data and Repr.rust_mut are both usize in the same location
     unsafe { Repr { raw: FatPtr { data, len } }.rust_mut }
 }
 
@@ -1233,6 +1233,7 @@ impl<T: ?Sized> *const T {
     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *const T where T: Sized {
+        // SAFETY: see documentation
         unsafe {
             intrinsics::arith_offset(self, count)
         }
@@ -1723,6 +1724,7 @@ impl<T: ?Sized> *const T {
         if !align.is_power_of_two() {
             panic!("align_offset: align is not a power-of-two");
         }
+        // SAFETY: align is a power of two
         unsafe {
             align_offset(self, align)
         }
@@ -1931,6 +1933,7 @@ impl<T: ?Sized> *mut T {
     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
     #[inline]
     pub fn wrapping_offset(self, count: isize) -> *mut T where T: Sized {
+        // SAFETY: see documentation
         unsafe {
             intrinsics::arith_offset(self, count) as *mut T
         }
@@ -2574,6 +2577,7 @@ impl<T: ?Sized> *mut T {
         if !align.is_power_of_two() {
             panic!("align_offset: align is not a power-of-two");
         }
+        // SAFETY: align is a power of two
         unsafe {
             align_offset(self, align)
         }

src/libcore/ptr/non_null.rs

@@ -7,8 +7,6 @@ use crate::mem;
 use crate::ptr::Unique;
 use crate::cmp::Ordering;
 
-// ignore-tidy-undocumented-unsafe
-
 /// `*mut T` but non-zero and covariant.
 ///
 /// This is often the correct thing to use when building data structures using
@@ -68,6 +66,7 @@ impl<T: Sized> NonNull<T> {
     #[stable(feature = "nonnull", since = "1.25.0")]
     #[inline]
     pub const fn dangling() -> Self {
+        // SAFETY: must not be dereferenced, but mem::align_of::<T>() > 0 if T is sized
         unsafe {
             let ptr = mem::align_of::<T>() as *mut T;
             NonNull::new_unchecked(ptr)
@@ -92,6 +91,7 @@ impl<T: ?Sized> NonNull<T> {
     #[inline]
     pub fn new(ptr: *mut T) -> Option<Self> {
         if !ptr.is_null() {
+            // SAFETY: just checked that ptr > 0
             Some(unsafe { Self::new_unchecked(ptr) })
         } else {
             None
@@ -131,6 +131,7 @@ impl<T: ?Sized> NonNull<T> {
     #[stable(feature = "nonnull_cast", since = "1.27.0")]
     #[inline]
     pub const fn cast<U>(self) -> NonNull<U> {
+        // SAFETY: self.pointer is non-null
         unsafe {
             NonNull::new_unchecked(self.as_ptr() as *mut U)
         }
@@ -207,6 +208,7 @@ impl<T: ?Sized> hash::Hash for NonNull<T> {
 impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
     #[inline]
     fn from(unique: Unique<T>) -> Self {
+        // SAFETY: Unique::as_ptr() can't be null
         unsafe { NonNull::new_unchecked(unique.as_ptr()) }
     }
 }
@@ -215,6 +217,7 @@ impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
 impl<T: ?Sized> From<&mut T> for NonNull<T> {
     #[inline]
     fn from(reference: &mut T) -> Self {
+        // SAFETY: references can't be null
         unsafe { NonNull { pointer: reference as *mut T } }
     }
 }
@@ -223,6 +226,7 @@ impl<T: ?Sized> From<&mut T> for NonNull<T> {
 impl<T: ?Sized> From<&T> for NonNull<T> {
     #[inline]
     fn from(reference: &T) -> Self {
+        // SAFETY: references can't be null
         unsafe { NonNull { pointer: reference as *const T } }
     }
 }

src/libcore/ptr/unique.rs

@@ -5,8 +5,6 @@ use crate::marker::{PhantomData, Unsize};
 use crate::mem;
 use crate::ptr::NonNull;
 
-// ignore-tidy-undocumented-unsafe
-
 /// A wrapper around a raw non-null `*mut T` that indicates that the possessor
 /// of this wrapper owns the referent. Useful for building abstractions like
 /// `Box<T>`, `Vec<T>`, `String`, and `HashMap<K, V>`.
@@ -71,6 +69,7 @@ impl<T: Sized> Unique<T> {
     // FIXME: rename to dangling() to match NonNull?
     #[inline]
     pub const fn empty() -> Self {
+        // SAFETY: must not be dereferenced, but mem::align_of::<T>() > 0 if T is sized
         unsafe {
             Unique::new_unchecked(mem::align_of::<T>() as *mut T)
         }
@@ -93,6 +92,7 @@ impl<T: ?Sized> Unique<T> {
     #[inline]
     pub fn new(ptr: *mut T) -> Option<Self> {
         if !ptr.is_null() {
+            // SAFETY: just checked that ptr > 0
             Some(unsafe { Unique { pointer: ptr as _, _marker: PhantomData } })
         } else {
             None
@@ -128,6 +128,7 @@ impl<T: ?Sized> Unique<T> {
     /// Casts to a pointer of another type.
     #[inline]
     pub const fn cast<U>(self) -> Unique<U> {
+        // SAFETY: self.pointer is non-null
         unsafe {
             Unique::new_unchecked(self.as_ptr() as *mut U)
         }
@@ -169,6 +170,7 @@ impl<T: ?Sized> fmt::Pointer for Unique<T> {
 impl<T: ?Sized> From<&mut T> for Unique<T> {
     #[inline]
     fn from(reference: &mut T) -> Self {
+        // SAFETY: references can't be null
         unsafe { Unique { pointer: reference as *mut T, _marker: PhantomData } }
     }
 }
@@ -177,6 +179,7 @@ impl<T: ?Sized> From<&mut T> for Unique<T> {
 impl<T: ?Sized> From<&T> for Unique<T> {
     #[inline]
     fn from(reference: &T) -> Self {
+        // SAFETY: references can't be null
         unsafe { Unique { pointer: reference as *const T, _marker: PhantomData } }
     }
 }
@@ -185,6 +188,7 @@ impl<T: ?Sized> From<&T> for Unique<T> {
 impl<T: ?Sized> From<NonNull<T>> for Unique<T> {
     #[inline]
     fn from(p: NonNull<T>) -> Self {
+        // SAFETY: NonNull::as_ptr() can't be null
         unsafe { Unique::new_unchecked(p.as_ptr()) }
     }
 }