[PATCH v3] rust: kernel: add SAFETY comments in aref doc example

[christopherjoshy]

From: Christopher Joshy <christopherjoshy4@xxxxxxxxx>

Add the missing `// SAFETY` comments in the `ARef::into_raw` doc
example, replacing the `TODO` placeholders from issue #351.

For the `unsafe impl AlwaysRefCounted`, explain that `Empty` owns no
data and has no destructor, so the no-op `inc_ref`/`dec_ref` cannot
free or leak anything, and that this doc example keeps the backing
object alive for the `ARef`'s lifetime.

For the `ARef::from_raw` call, explain that `ptr` is derived from a
valid reference (so it is valid) and that the required refcount
increment is trivially owned because `Empty`'s `AlwaysRefCounted`
manages no actual refcount.

Link: https://github.com/Rust-for-Linux/linux/issues/351
Suggested-by: Miguel Ojeda <ojeda@xxxxxxxxxx>
Signed-off-by: Christopher Joshy <christopherjoshy4@xxxxxxxxx>
---
 rust/kernel/sync/aref.rs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs
index b721b2e00..3cf7bc27f 100644
--- a/rust/kernel/sync/aref.rs
+++ b/rust/kernel/sync/aref.rs
@@ -124,7 +124,10 @@ pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
     ///
     /// struct Empty {}
     ///
-    /// # // SAFETY: TODO.
+    /// // SAFETY: `Empty` owns no data and has no destructor, so its `inc_ref`/`dec_ref`
+    /// // are no-ops that cannot free or leak anything. This doc example keeps the backing
+    /// // `Empty` (`data`) alive for the whole lifetime of `data_ref`, so the `ARef` never
+    /// // dereferences freed memory.
     /// unsafe impl AlwaysRefCounted for Empty {
     ///     fn inc_ref(&self) {}
     ///     unsafe fn dec_ref(_obj: NonNull<Self>) {}
@@ -132,7 +135,10 @@ pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
     ///
     /// let mut data = Empty {};
     /// let ptr = NonNull::<Empty>::new(&mut data).unwrap();
-    /// # // SAFETY: TODO.
+    /// // SAFETY: `ptr` comes from a valid `&mut data` reference, hence it is non-null,
+    /// // aligned and points to a valid `Empty`. `ARef::from_raw` also requires owning a
+    /// // refcount increment; this is trivially met because `Empty`'s `AlwaysRefCounted` uses
+    /// // no-op `inc_ref`/`dec_ref` and so manages no actual refcount.
     /// let data_ref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };
     /// let raw_ptr: NonNull<Empty> = ARef::into_raw(data_ref);
     ///
-- 
2.43.0