refactor: add unfinished safety comments for initialization and pinning macros

Author: liamjdavis

src/__internal.rs

@@ -116,12 +116,12 @@ impl<T: ?Sized> Clone for AllData<T> {
 
 impl<T: ?Sized> Copy for AllData<T> {}
 
-// SAFETY: TODO.
+// SAFETY: `AllData<T>` is a zero-sized type that carries no runtime data, only type information.
 unsafe impl<T: ?Sized> InitData for AllData<T> {
     type Datee = T;
 }
 
-// SAFETY: TODO.
+// SAFETY: `__init_data` returns only phantom data, it performs no memory operations.
 unsafe impl<T: ?Sized> HasInitData for T {
     type InitData = AllData<T>;
 

src/lib.rs

@@ -763,7 +763,8 @@ macro_rules! stack_try_pin_init {
 ///
 /// let init = pin_init!(&this in Buf {
 ///     buf: [0; 64],
-///     // SAFETY: TODO.
+///     // SAFETY: The closure properly initializes to the target memory location,
+///     // and error handling ensures memory is left ina  valid state if initization fails.
 ///     ptr: unsafe { addr_of_mut!((*this.as_ptr()).buf).cast() },
 ///     pin: PhantomPinned,
 /// });
@@ -1393,7 +1394,7 @@ where
 // SAFETY: Every type can be initialized by-value.
 unsafe impl<T, E> Init<T, E> for T {
     unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
-        // SAFETY: TODO.
+        // SAFETY: `slot` points to a valid, uninitialized memory of the correct size and alignment for type `T`.
         unsafe { slot.write(self) };
         Ok(())
     }
@@ -1402,7 +1403,7 @@ unsafe impl<T, E> Init<T, E> for T {
 // SAFETY: Every type can be initialized by-value. `__pinned_init` calls `__init`.
 unsafe impl<T, E> PinInit<T, E> for T {
     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
-        // SAFETY: TODO.
+        // SAFETY: `self` is a valid value of type `T`, and all requirements for `__init` are met.
         unsafe { self.__init(slot) }
     }
 }

src/macros.rs

@@ -518,7 +518,8 @@ macro_rules! __pinned_drop {
             }
         ),
     ) => {
-        // SAFETY: TODO.
+        // SAFETY: The `OnlyCallFromDrop` token ensures the drop function can only be called
+        // when the struct is properly pinned.
         unsafe $($impl_sig)* {
             // Inherit all attributes and the type/ident tokens for the signature.
             $(#[$($attr)*])*
@@ -878,7 +879,8 @@ macro_rules! __pin_data {
                 }
             }
 
-            // SAFETY: TODO.
+            // SAFETY: `__ThePinData` correctly represents the pinning structure of the original type
+            // and the associated type `Datee` correctly refers to the original struct type.
             unsafe impl<$($impl_generics)*>
                 $crate::__internal::PinData for __ThePinData<$($ty_generics)*>
             where $($whr)*
@@ -1005,7 +1007,7 @@ macro_rules! __pin_data {
                     slot: *mut $p_type,
                     init: impl $crate::PinInit<$p_type, E>,
                 ) -> ::core::result::Result<(), E> {
-                    // SAFETY: TODO.
+                    // SAFETY: `slot` points to valid, uninitialized memory for a `$p_type`.
                     unsafe { $crate::PinInit::__pinned_init(init, slot) }
                 }
             )*
@@ -1016,7 +1018,7 @@ macro_rules! __pin_data {
                     slot: *mut $type,
                     init: impl $crate::Init<$type, E>,
                 ) -> ::core::result::Result<(), E> {
-                    // SAFETY: TODO.
+                    // SAFETY: `slot` points to valid, uninitialized memory for a `$type`.
                     unsafe { $crate::Init::__init(init, slot) }
                 }
             )*
@@ -1132,7 +1134,8 @@ macro_rules! __init_internal {
         struct __InitOk;
         // Get the data about fields from the supplied type.
         //
-        // SAFETY: TODO.
+        // SAFETY: The `$get_data()` function only returns metadata about the type's pinning structure.
+        // No memory is accessed, only type-level information is retrieved.
         let data = unsafe {
             use $crate::__internal::$has_data;
             // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal
@@ -1188,7 +1191,8 @@ macro_rules! __init_internal {
         let init = move |slot| -> ::core::result::Result<(), $err> {
             init(slot).map(|__InitOk| ())
         };
-        // SAFETY: TODO.
+        // SAFETY: The closure property initializes the target memory location. Error handling
+        // ensures memory is left in a valid state if initialization fails.
         let init = unsafe { $crate::$construct_closure::<_, $err>(init) };
         init
     }};
@@ -1338,7 +1342,8 @@ macro_rules! __init_internal {
         // Since we are in the closure that is never called, this will never get executed.
         // We abuse `slot` to get the correct type inference here:
         //
-        // SAFETY: TODO.
+        // SAFETY: This is unreachable code that is used solely for compile-time type checking,
+        // it is never executed.
         unsafe {
             // Here we abuse `paste!` to retokenize `$t`. Declarative macros have some internal
             // information that is associated to already parsed fragments, so a path fragment