From 26ab71043d97c1b06bdd252378b64171cb95b1a9 Mon Sep 17 00:00:00 2001
From: Christian Cunningham <cc@localhost>
Date: Fri, 19 Aug 2022 21:22:18 -0700
Subject: Updated docs

---
 src/sync.rs | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

(limited to 'src/sync.rs')

diff --git a/src/sync.rs b/src/sync.rs
index 2b7e1ff..cd626fa 100644
--- a/src/sync.rs
+++ b/src/sync.rs
@@ -1,20 +1,44 @@
+//! # Synchronization module
+//!
+//! Provides synchronization objects for thread-safe memory sharing.
+use core::cell::UnsafeCell;
+
+/// # Synchronization interfaces
+///
+/// Provides Synchronization traits.
 pub mod interface {
+	/// # Mutex Trait
+	///
+	/// Basic Locking primitive to allow single-process access to data
 	pub trait Mutex {
+		/// # The data
+		///
+		/// Each mutex protects some internal data from modification across
+		/// processes when it is in use. This is important if the process
+		/// is preempted while the function is using it.
 		type Data;
+		/// # Locking mechanism
+		///
+		/// Locks the mutex to access the data in a closure.
+		/// The data can be read and modified in this closure without worry
+		/// of poisoning the data across processes.
 		fn lock<'a, R>(&'a self, f: impl FnOnce(&'a mut Self::Data) -> R) -> R;
 	}
 }
 
-use core::cell::UnsafeCell;
-
+/// # Basic Lock Structure
 pub struct NullLock<T> where T: ?Sized {
+	/// The internal data to safely share
 	data: UnsafeCell<T>,
 }
 
+/// # Allow thread sharing
 unsafe impl<T> Send for NullLock<T> where T: ?Sized + Send {}
+/// # Allow thread sharing
 unsafe impl<T> Sync for NullLock<T> where T: ?Sized + Send {}
 
 impl<T> NullLock<T> {
+	/// # Create a new instance of the lock
 	pub const fn new(data: T) -> Self {
 		Self {
 			data: UnsafeCell::new(data),
@@ -23,8 +47,13 @@ impl<T> NullLock<T> {
 }
 
 impl<T> interface::Mutex for NullLock<T> {
+	/// # Underlying data of the lock
 	type Data = T;
 
+	/// # Locking mechanism
+	///
+	/// Locks the Mutex, and passes a mutable reference
+	/// to the encapsulated data to a closure.
 	fn lock<'a, R>(&'a self, f: impl FnOnce(&'a mut T) -> R) -> R {
 		let data = unsafe { &mut *self.data.get() };
 
-- 
cgit v1.2.1