Clean up existing documentation

1 files changed, 42 insertions, 29 deletions

diff --git a/src/mutex/mutex.rs b/src/mutex/mutex.rs
index a2813a1..05b10db 100644
--- a/src/mutex/mutex.rs
+++ b/src/mutex/mutex.rs
@@ -108,7 +108,7 @@ impl<T, R: RawMutex> LockableGetMut for Mutex<T, R> {
 unsafe impl<T, R: RawMutex> OwnedLockable for Mutex<T, R> {}
 
 impl<T, R: RawMutex> Mutex<T, R> {
-	/// Create a new unlocked `Mutex`.
+	/// Creates a `Mutex` in an unlocked state ready for use.
 	///
 	/// # Examples
 	///
@@ -283,25 +283,30 @@ impl<T: ?Sized, R: RawMutex> Mutex<T, R> {
 }
 
 impl<T: ?Sized, R: RawMutex> Mutex<T, R> {
-	/// Block the thread until this mutex can be locked, and lock it.
+	/// Acquires a mutex, blocking the current thread until it is able to do so.
 	///
-	/// Upon returning, the thread is the only thread with a lock on the
-	/// `Mutex`. A [`MutexGuard`] is returned to allow a scoped unlock of this
-	/// `Mutex`. When the guard is dropped, this `Mutex` will unlock.
+	/// This function will block the local thread until it is available to acquire
+	/// the mutex. Upon returning, the thread is the only thread with the lock
+	/// held. A [`MutexGuard`] is returned to allow a scoped unlock of this
+	/// `Mutex`. When the guard goes out of scope, this `Mutex` will unlock.
+	///
+	/// Due to the requirement of a [`ThreadKey`] to call this function, it is not
+	/// possible for this function to deadlock.
 	///
 	/// # Examples
 	///
 	/// ```
-	/// use std::{thread, sync::Arc};
+	/// use std::thread;
 	/// use happylock::{Mutex, ThreadKey};
 	///
-	/// let mutex = Arc::new(Mutex::new(0));
-	/// let c_mutex = Arc::clone(&mutex);
+	/// let mutex = Mutex::new(0);
 	///
-	/// thread::spawn(move || {
-	///     let key = ThreadKey::get().unwrap();
-	///     *c_mutex.lock(key) = 10;
-	/// }).join().expect("thread::spawn failed");
+	/// thread::scope(|s| {
+	///     s.spawn(|| {
+	///         let key = ThreadKey::get().unwrap();
+	///         *mutex.lock(key) = 10;
+	///     });
+	/// });
 	///
 	/// let key = ThreadKey::get().unwrap();
 	/// assert_eq!(*mutex.lock(key), 10);
@@ -316,35 +321,36 @@ impl<T: ?Sized, R: RawMutex> Mutex<T, R> {
 		}
 	}
 
-	/// Attempts to lock the `Mutex` without blocking.
+	/// Attempts to lock this `Mutex` without blocking.
 	///
-	/// If the access could not be granted at this time, then `Err` is
-	/// returned. Otherwise, an RAII guard is returned which will release the
-	/// lock when it is dropped.
+	/// If the lock could not be acquired at this time, then `Err` is returned.
+	/// Otherwise, an RAII guard is returned. The lock will be unlocked when the
+	/// guard is dropped.
 	///
 	/// # Errors
 	///
 	/// If the mutex could not be acquired because it is already locked, then
-	/// this call will return an error containing the given key.
+	/// this call will return an error containing the [`ThreadKey`].
 	///
 	/// # Examples
 	///
 	/// ```
-	/// use std::{thread, sync::Arc};
+	/// use std::thread;
 	/// use happylock::{Mutex, ThreadKey};
 	///
-	/// let mutex = Arc::new(Mutex::new(0));
-	/// let c_mutex = Arc::clone(&mutex);
+	/// let mutex = Mutex::new(0);
 	///
-	/// thread::spawn(move || {
-	///     let key = ThreadKey::get().unwrap();
-	///     let mut lock = c_mutex.try_lock(key);
-	///     if let Ok(mut lock) = lock {
-	///         *lock = 10;
-	///     } else {
-	///         println!("try_lock failed");
-	///     }
-	/// }).join().expect("thread::spawn failed");
+	/// thread::scope(|s| {
+	///     s.spawn(|| {
+	///         let key = ThreadKey::get().unwrap();
+	///         let mut lock = mutex.try_lock(key);
+	///         if let Ok(mut lock) = lock {
+	///             *lock = 10;
+	///         } else {
+	///             println!("try_lock failed");
+	///         }
+	///     });
+	/// });
 	///
 	/// let key = ThreadKey::get().unwrap();
 	/// assert_eq!(*mutex.lock(key), 10);
@@ -375,6 +381,10 @@ impl<T: ?Sized, R: RawMutex> Mutex<T, R> {
 
 	/// Consumes the [`MutexGuard`], and consequently unlocks its `Mutex`.
 	///
+	/// This function is equivalent to calling [`drop`] on the guard, except that
+	/// it returns the key that was used to create it. Alernatively, the guard
+	/// will be automatically dropped when it goes out of scope.
+	///
 	/// # Examples
 	///
 	/// ```
@@ -387,6 +397,9 @@ impl<T: ?Sized, R: RawMutex> Mutex<T, R> {
 	/// *guard += 20;
 	///
 	/// let key = Mutex::unlock(guard);
+	///
+	/// let guard = mutex.lock(key);
+	/// assert_eq!(*guard, 20);
 	/// ```
 	#[must_use]
 	pub fn unlock(guard: MutexGuard<'_, T, R>) -> ThreadKey {