From 3d65cf3329036c700a98739909842ed3ca295476 Mon Sep 17 00:00:00 2001
From: pantonshire <tom@tomandtally.co.uk>
Date: Tue, 29 Aug 2023 08:55:02 +0100
Subject: [PATCH] README and module documentation

---
 README.md  | 35 ++++++++++++++++++++++++++++++++++-
 src/lib.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 996f9a8..f5c144f 100644
--- a/README.md
+++ b/README.md
@@ -9,5 +9,38 @@ to the template files in quick succession, it would be wasteful to reload the te
 change; instead, a debouncer could be used to group the changes that occur at a similar time into
 a single change, so the templates are only reloaded once.
 
-## Usage
+A new debouncer can be created with the
+`debouncer`
+function, which returns the debouncer in two halves: a tx (send) half and rx (receive) half. The
+tx sends raw un-debounced events to the debouncer, and the rx receives the debounced events from
+the debouncer. Both halves can be cloned to allow for multiple senders and receivers.
 
+```rust
+# use std::{thread, time::Duration};
+// Create a new debouncer which takes raw events of type `u32` and outputs
+// debounced events of type `Vec<u32>`.
+let (tx, rx) = treacle::debouncer::<u32, Vec<u32>, _>(
+    // Group events which occur in the same 500ms window.
+    Duration::from_millis(500),
+    // Combine raw events by pushing them to a vector.
+    |acc, raw_event| {
+        let mut events_vector = acc.unwrap_or_default();
+        events_vector.push(raw_event);
+        events_vector
+    });
+
+thread::spawn(move || {
+    // Send two raw events in quick succession.
+    tx.send(10).unwrap();
+    tx.send(20).unwrap();
+
+    // Wait, then send more raw events.
+    thread::sleep(Duration::from_millis(500));
+    tx.send(30).unwrap();
+    tx.send(40).unwrap();
+    tx.send(50).unwrap();
+});
+
+assert_eq!(rx.recv().unwrap(), &[10, 20]);
+assert_eq!(rx.recv().unwrap(), &[30, 40, 50]);
+```
diff --git a/src/lib.rs b/src/lib.rs
index 30fe10e..29a279d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,48 @@
+//! A generic event debouncer, for grouping events which occur close together in time into a single
+//! event.
+//! 
+//! For example, you may have some
+//! [templates](https://www.arewewebyet.org/topics/templating/)
+//! which you want to reload whenever a template file changes. However, if many small changes are
+//! made to the template files in quick succession, it would be wasteful to reload the templates
+//! for every change; instead, a debouncer could be used to group the changes that occur at a
+//! similar time into a single change, so the templates are only reloaded once.
+//! 
+//! A new debouncer can be created with the [`debouncer`](debouncer) function, which returns the
+//! debouncer in two halves: a tx (send) half and rx (receive) half. The tx sends raw un-debounced
+//! events to the debouncer, and the rx receives the debounced events from the debouncer. Both
+//! halves can be cloned to allow for multiple senders and receivers.
+//! 
+//! ```
+//! # use std::{thread, time::Duration};
+//! // Create a new debouncer which takes raw events of type `u32` and outputs
+//! // debounced events of type `Vec<u32>`.
+//! let (tx, rx) = treacle::debouncer::<u32, Vec<u32>, _>(
+//!     // Group events which occur in the same 500ms window.
+//!     Duration::from_millis(500),
+//!     // Combine raw events by pushing them to a vector.
+//!     |acc, raw_event| {
+//!         let mut events_vector = acc.unwrap_or_default();
+//!         events_vector.push(raw_event);
+//!         events_vector
+//!     });
+//! 
+//! thread::spawn(move || {
+//!     // Send two raw events in quick succession.
+//!     tx.send(10).unwrap();
+//!     tx.send(20).unwrap();
+//! 
+//!     // Wait, then send more raw events.
+//!     thread::sleep(Duration::from_millis(500));
+//!     tx.send(30).unwrap();
+//!     tx.send(40).unwrap();
+//!     tx.send(50).unwrap();
+//! });
+//! 
+//! assert_eq!(rx.recv().unwrap(), &[10, 20]);
+//! assert_eq!(rx.recv().unwrap(), &[30, 40, 50]);
+//! ```
+
 pub mod fold;
 
 use std::{