Comments

1 files changed, 12 insertions, 0 deletions

diff --git a/src/context.rs b/src/context.rs
index 2f9ca64..1707022 100644
--- a/src/context.rs
+++ b/src/context.rs
@@ -66,7 +66,16 @@ pub mod tuple;
 /// ```
 ///
 /// [`OwnedLockCollection::context`]: crate::collection::OwnedLockCollection::context
+// This is only available from OwnedLockCollection because it ensures the lock
+// order is the same as the one provided by this function. Tuples may have
+// their elements re-ordered by the compiler.
+//
+// This struct is just a fancy place to hold the ThreadKey while it's being
+// borrowed by multiple other guards.
 pub struct LockContext<'l, L> {
+	// Unfortunately there is no better way to get this into the context than to
+	// use an option, initialize to `None` and insert it later. If we returned a
+	// new type, that would move the thread key while it's being borrowed.
 	key: Option<ThreadKey>,
 	lockable: &'l L,
 }
@@ -165,6 +174,9 @@ pub struct LockingTuple<'context, L, C, Outer = ()> {
 /// [`lock`]: `crate::mutex::Mutex::lock`
 /// [`try_lock`]: `crate::Mutex::try_lock`
 pub struct ContextGuard<'a, Guard, Key> {
+	// The idea behind having this be a shared reference is that it allows
+	// guards to exist at once. And while these borrows exist, the thread key will
+	// not be able to be reused somewhere else.
 	_key: &'a Key,
 	guard: Guard,
 }