From 680e335ccfb6f7472ce439504af2ae99942e9466 Mon Sep 17 00:00:00 2001
From: Bert Peters <bert@bertptrs.nl>
Date: Sat, 10 Jul 2021 17:19:34 +0200
Subject: [PATCH] Document new modules

---
 CHANGELOG.md      | 11 +++++++++++
 src/lockapi.rs    |  9 +++++++++
 src/parkinglot.rs | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e45d5f6..d3264fd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+- Added generic support for wrapping mutexes that implement the traits provided by the
+  [`lock_api`][lock_api] crate. This can be used for creating support for other mutex providers that
+  implement it.
+
+- Added support for [`parking_lot`][parking_lot] mutexes. Support includes type aliases for all
+  provided mutex types as well as a dedicated `Once` wrapper.
+
 ## [0.1.2] - 2021-05-27
 
 ### Added
@@ -33,3 +41,6 @@ Initial release.
 [0.1.2]: https://github.com/bertptrs/tracing-mutex/compare/v0.1.2...v0.1.2
 [0.1.1]: https://github.com/bertptrs/tracing-mutex/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/bertptrs/tracing-mutex/releases/tag/v0.1.0
+
+[lock_api]: https://docs.rs/lock_api/
+[parking_lot]: https://docs.rs/parking_lot/
diff --git a/src/lockapi.rs b/src/lockapi.rs
index c9f82f4..b76cb8c 100644
--- a/src/lockapi.rs
+++ b/src/lockapi.rs
@@ -1,4 +1,13 @@
 //! Wrapper implementations for [`lock_api`].
+//!
+//! This module does not provide any particular mutex implementation by itself, but rather can be
+//! used to add dependency tracking to mutexes that already exist. It implements all of the traits
+//! in `lock_api` based on the one it wraps. Crates such as `spin` and `parking_lot` provide base
+//! primitives that can be wrapped.
+//!
+//! Wrapped mutexes are at least one `usize` larger than the types they wrapped, and must be aligned
+//! to `usize` boundaries. As such, libraries with many mutexes may want to consider the additional
+//! required memory.
 use lock_api::GuardNoSend;
 use lock_api::RawMutex;
 use lock_api::RawMutexFair;
diff --git a/src/parkinglot.rs b/src/parkinglot.rs
index 5d44ab1..d046f1a 100644
--- a/src/parkinglot.rs
+++ b/src/parkinglot.rs
@@ -1,3 +1,42 @@
+//! Wrapper types and type aliases for tracing [`parking_lot`] mutexes.
+//!
+//! This module provides type aliases that use the [`lockapi`][crate::lockapi] module to provide
+//! tracing variants of the `parking_lot` primitives. Each of the `TracingX` type aliases wraps an
+//! `X` in the `parkint_lot` api with dependency tracking, and a `DebugX` will refer to a `TracingX`
+//! when  `debug_assertions` are enabled and to `X` when they're not. This can be used to aid
+//! debugging in development while enjoying maximum performance in production.
+//!
+//! # Usage
+//!
+//! ```
+//! # use std::sync::Arc;
+//! # use std::thread;
+//! # use lock_api::Mutex;
+//! # use tracing_mutex::parkinglot::TracingMutex;
+//! let mutex = Arc::new(TracingMutex::new(0));
+//!
+//! let handles: Vec<_> = (0..10).map(|_| {
+//!    let mutex = Arc::clone(&mutex);
+//!    thread::spawn(move || *mutex.lock() += 1)
+//! }).collect();
+//!
+//! handles.into_iter().for_each(|handle| handle.join().unwrap());
+//!
+//! // All threads completed so the value should be 10.
+//! assert_eq!(10, *mutex.lock());
+//! ```
+//!
+//! # Limitations
+//!
+//! The main lock for the global state is still provided by `std::sync` and the tracing primitives
+//! are larger than the `parking_lot` primitives they wrap, so there can be a performance
+//! degradation between using this and using `parking_lot` directly. If this is of concern to you,
+//! try using the `DebugX`-structs, which provide cycle detection only when `debug_assertions` are
+//! enabled and have no overhead when they're not.
+//!
+//! In addition, the mutex guards returned by the tracing wrappers are `!Send`, regardless of
+//! whether `parking_lot` is configured to have `Send` mutex guards. This is a limitation of the
+//! current bookkeeping system.
 use parking_lot::Once;
 use parking_lot::OnceState;