From 1e2ab78a3fad8f383e5949dd0a11aaaaf03467f1 Mon Sep 17 00:00:00 2001
From: Per Lindgren <per.lindgren@ltu.se>
Date: Tue, 2 Nov 2021 19:47:14 +0100
Subject: [PATCH] added doc for RacyCell

---
 src/lib.rs | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index d5505b03cf..8463442acf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -59,6 +59,27 @@ where
 use core::cell::UnsafeCell;
 
 /// Internal replacement for `static mut T`
+///
+/// Used to represent RTIC Resources
+///
+/// Soundness:
+/// 1) Unsafe API for internal use only
+/// 2) get_mut(&self) -> *mut T
+///    returns a raw mutable pointer to the inner T
+///    casting to &mut T is under control of RTIC
+///    RTIC ensures &mut T to be unique under Rust aliasing rules.
+///
+///    Implementation uses the underlying UnsafeCell<T>
+///    self.0.get() -> *mut T
+///
+/// 3) get(&self) -> *const T
+///    returns a raw immutable (const) pointer to the inner T
+///    casting to &T is under control of RTIC
+///    RTIC ensures &T to be shared under Rust aliasing rules.
+///
+///    Implementation uses the underlying UnsafeCell<T>
+///    self.0.get() -> *mut T, demoted to *const T
+///    
 #[repr(transparent)]
 pub struct RacyCell<T>(UnsafeCell<T>);