Documentation

1 files changed, 19 insertions, 0 deletions

diff --git a/src/rwlock/write_lock.rs b/src/rwlock/write_lock.rs
index dd204f5..0275a70 100644
--- a/src/rwlock/write_lock.rs
+++ b/src/rwlock/write_lock.rs
@@ -25,6 +25,16 @@ impl<'a, T: ?Sized, R> AsRef<RwLock<T, R>> for WriteLock<'a, T, R> {
 }
 
 impl<'a, T: ?Sized, R> WriteLock<'a, T, R> {
+	/// Creates a new `WriteLock` which accesses the given [`RwLock`]
+	///
+	/// # Examples
+	///
+	/// ```
+	/// use happylock::{rwlock::WriteLock, RwLock};
+	///
+	/// let lock = RwLock::new(5);
+	/// let write_lock = WriteLock::new(&lock);
+	/// ```
 	#[must_use]
 	pub const fn new(rwlock: &'a RwLock<T, R>) -> Self {
 		Self(rwlock)
@@ -32,6 +42,8 @@ impl<'a, T: ?Sized, R> WriteLock<'a, T, R> {
 }
 
 impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> {
+	/// Locks the underlying [`RwLock`] with exclusive write access, blocking
+	/// the current until it can be acquired.
 	pub fn lock<'s, 'key: 's, Key: Keyable + 'key>(
 		&'s self,
 		key: Key,
@@ -39,10 +51,13 @@ impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> {
 		self.0.write(key)
 	}
 
+	/// Creates an exclusive lock without a key. Locking this without exclusive
+	/// access to the key is undefined behavior.
 	pub(crate) unsafe fn lock_no_key(&self) -> RwLockWriteRef<'_, T, R> {
 		self.0.write_no_key()
 	}
 
+	/// Attempts to lock the underlying [`RwLock`] with exclusive write access.
 	pub fn try_lock<'s, 'key: 's, Key: Keyable + 'key>(
 		&'s self,
 		key: Key,
@@ -50,10 +65,14 @@ impl<'a, T: ?Sized, R: RawRwLock> WriteLock<'a, T, R> {
 		self.0.try_write(key)
 	}
 
+	/// Attempts to create an exclusive lock without a key. Locking this
+	/// without exclusive access to the key is undefined behavior.
 	pub(crate) unsafe fn try_lock_no_key(&self) -> Option<RwLockWriteRef<'_, T, R>> {
 		self.0.try_write_no_key()
 	}
 
+	/// Immediately drops the guard, and consequently releases the exclusive
+	/// lock.
 	pub fn unlock<'key, Key: Keyable + 'key>(guard: RwLockWriteGuard<'_, 'key, T, Key, R>) -> Key {
 		RwLock::unlock_write(guard)
 	}