Docs for ThreadKey

1 files changed, 18 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
index be3d05b..614820f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -8,6 +8,10 @@ thread_local! {
 	pub static KEY: Mutex<Option<ThreadKey>> = Mutex::new(Some(unsafe { ThreadKey::new() }));
 }
 
+/// The key for the current thread.
+///
+/// Only one of these exist per thread. To get the current thread's key, call
+/// [`ThreadKey::lock`].
 pub struct ThreadKey {
 	_priv: *const (), // this isn't Send or Sync
 }
@@ -19,16 +23,30 @@ impl Debug for ThreadKey {
 }
 
 impl ThreadKey {
+	/// Create a new `ThreadKey`.
+	///
+	/// # Safety
+	///
+	/// There should only be one `ThreadKey` per thread.
 	unsafe fn new() -> Self {
 		Self {
 			_priv: std::ptr::null(),
 		}
 	}
 
+	/// Get the current thread's `ThreadKey, if it's not already taken.
+	///
+	/// The first time this is called, it will successfully return a
+	/// `ThreadKey`. However, future calls to this function will return
+	/// [`None`], unless the key is unlocked first.
 	pub fn lock() -> Option<Self> {
 		KEY.with(|thread_lock| thread_lock.lock().take())
 	}
 
+	/// Unlocks the `ThreadKey`.
+	///
+	/// After this method is called, a call to [`ThreadKey::lock`] will return
+	/// this `ThreadKey`.
 	pub fn unlock(lock: ThreadKey) {
 		KEY.with(|thread_lock| {
 			let mut thread_lock = thread_lock.lock();