Documentation

1 files changed, 38 insertions, 2 deletions

diff --git a/src/rwlock/read_lock.rs b/src/rwlock/read_lock.rs
index dbab8de..176fc01 100644
--- a/src/rwlock/read_lock.rs
+++ b/src/rwlock/read_lock.rs
@@ -6,9 +6,25 @@ use crate::key::Keyable;
 
 use super::{ReadLock, RwLock, RwLockReadGuard, RwLockReadRef};
 
-impl<'a, T: ?Sized, R> Debug for ReadLock<'a, T, R> {
+impl<'a, T: ?Sized + Debug, R: RawRwLock> Debug for ReadLock<'a, T, R> {
 	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		f.write_str(&format!("ReadLock<{}>", std::any::type_name::<T>()))
+		// safety: this is just a try lock, and the value is dropped
+		//         immediately after, so there's no risk of blocking ourselves
+		//         or any other threads
+		if let Some(value) = unsafe { self.try_lock_no_key() } {
+			f.debug_struct("ReadLock").field("data", &&*value).finish()
+		} else {
+			struct LockedPlaceholder;
+			impl Debug for LockedPlaceholder {
+				fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+					f.write_str("<locked>")
+				}
+			}
+
+			f.debug_struct("ReadLock")
+				.field("data", &LockedPlaceholder)
+				.finish()
+		}
 	}
 }
 
@@ -25,6 +41,16 @@ impl<'a, T: ?Sized, R> AsRef<RwLock<T, R>> for ReadLock<'a, T, R> {
 }
 
 impl<'a, T: ?Sized, R> ReadLock<'a, T, R> {
+	/// Creates a new `ReadLock` which accesses the given [`RwLock`]
+	///
+	/// # Examples
+	///
+	/// ```
+	/// use happylock::{rwlock::ReadLock, RwLock};
+	///
+	/// let lock = RwLock::new(5);
+	/// let read_lock = ReadLock::new(&lock);
+	/// ```
 	#[must_use]
 	pub const fn new(rwlock: &'a RwLock<T, R>) -> Self {
 		Self(rwlock)
@@ -32,6 +58,8 @@ impl<'a, T: ?Sized, R> ReadLock<'a, T, R> {
 }
 
 impl<'a, T: ?Sized, R: RawRwLock> ReadLock<'a, T, R> {
+	/// Locks the underlying [`RwLock`] with shared read access, blocking the
+	/// current thread until it can be acquired.
 	pub fn lock<'s, 'key: 's, Key: Keyable + 'key>(
 		&'s self,
 		key: Key,
@@ -39,10 +67,14 @@ impl<'a, T: ?Sized, R: RawRwLock> ReadLock<'a, T, R> {
 		self.0.read(key)
 	}
 
+	/// Creates a shared lock without a key. Locking this without exclusive
+	/// access to the key is undefined behavior.
 	pub(crate) unsafe fn lock_no_key(&self) -> RwLockReadRef<'_, T, R> {
 		self.0.read_no_key()
 	}
 
+	/// Attempts to acquire the underlying [`RwLock`] with shared read access
+	/// without blocking.
 	pub fn try_lock<'s, 'key: 's, Key: Keyable + 'key>(
 		&'s self,
 		key: Key,
@@ -50,10 +82,14 @@ impl<'a, T: ?Sized, R: RawRwLock> ReadLock<'a, T, R> {
 		self.0.try_read(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<RwLockReadRef<'_, T, R>> {
 		self.0.try_read_no_key()
 	}
 
+	/// Immediately drops the guard, and consequentlyreleases the shared lock
+	/// on the underlying [`RwLock`].
 	pub fn unlock<'key, Key: Keyable + 'key>(guard: RwLockReadGuard<'_, 'key, T, Key, R>) -> Key {
 		RwLock::unlock_read(guard)
 	}