Add documentation

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "redsync"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["jace-ys <[email protected]>"]
 edition = "2018"
 description = "A Rust implementation of Redlock for distributed locks with Redis"

README.md

@@ -6,3 +6,39 @@
 # Redsync
 
 A Rust implementation of [Redlock](https://redis.io/topics/distlock) for distributed locks with Redis.
+
+## Installation
+
+Add the following line to your Cargo.toml file:
+
+```toml
+[dependencies]
+redsync = "0.1.1"
+```
+
+## Documentation
+
+See https://docs.rs/redsync.
+
+# Quick Start
+
+```rust
+use std::error::Error;
+use std::time::Duration;
+use redsync::{RedisInstance, Redsync};
+
+fn main() -> Result<(), Box<dyn Error>> {
+  let dlm = Redsync::new(vec![
+    RedisInstance::new("redis://127.0.0.1:6389")?,
+    RedisInstance::new("redis://127.0.0.1:6399")?,
+    RedisInstance::new("redis://127.0.0.1:6379")?,
+  ]);
+
+  let lock = dlm.lock("resource", Duration::from_secs(1))?;
+  dlm.unlock(&lock)?;
+
+  Ok(())
+}
+```
+
+For more examples, see [examples](https://github.com/jace-ys/redsync/tree/master/examples).

src/builder.rs

@@ -3,6 +3,7 @@ use crate::redsync::Redsync;
 
 use std::time::Duration;
 
+/// `RedsyncBuilder` is a builder for configuring and constructing a Redsync instance.
 pub struct RedsyncBuilder<I: Instance> {
     cluster: Vec<I>,
     retry_count: u32,

src/errors.rs

@@ -3,6 +3,7 @@ use std::ops::{Deref, DerefMut};
 
 use thiserror::Error;
 
+/// `RedsyncError` is an enum of all error kinds returned by the crate.
 #[derive(Error, Debug, PartialEq)]
 pub enum RedsyncError {
     #[error("{0}")]
@@ -23,6 +24,7 @@ pub enum RedsyncError {
     UnlockFailed(MultiError),
 }
 
+/// `MultiError` wraps Vec<RedsyncError>, typically aggregated over instances in a Redsync cluster.
 #[derive(Debug, Default, PartialEq)]
 pub struct MultiError(Vec<RedsyncError>);
 

src/instance.rs

@@ -3,6 +3,7 @@ use crate::redsync::Lock;
 
 use std::time::Duration;
 
+/// `Instance` represents an entity with locking and unlocking capabilities.
 pub trait Instance {
     fn acquire(&self, lock: &Lock) -> Result<(), RedsyncError>;
     fn extend(&self, lock: &Lock) -> Result<(), RedsyncError>;
@@ -26,6 +27,7 @@ else
     return 0
 end";
 
+/// `RedisInstance` is the implementation of the Instance trait for a Redis server.
 pub struct RedisInstance {
     client: redis::Client,
 }

src/lib.rs

@@ -1,3 +1,33 @@
+//! # Installation
+//!
+//! Add the following line to your Cargo.toml file:
+//! ```
+//! [dependencies]
+//! redsync = "0.1.1"
+//! ```
+//!
+//! # Quick Start
+//!
+//! ```
+//! use std::error::Error;
+//! use std::time::Duration;
+//! use redsync::{RedisInstance, Redsync};
+//!
+//! fn main() -> Result<(), Box<dyn Error>> {
+//!   let dlm = Redsync::new(vec![
+//!     RedisInstance::new("redis://127.0.0.1:6389")?,
+//!     RedisInstance::new("redis://127.0.0.1:6399")?,
+//!     RedisInstance::new("redis://127.0.0.1:6379")?,
+//!   ]);
+//!
+//!   let lock = dlm.lock("resource", Duration::from_secs(1))?;
+//!   dlm.unlock(&lock)?;
+//!
+//!   Ok(())
+//! }
+//! ```
+//!
+//! For more examples, see [examples](https://github.com/jace-ys/redsync/tree/master/examples).
 pub use crate::builder::RedsyncBuilder;
 pub use crate::errors::{MultiError, RedsyncError};
 pub use crate::instance::{Instance, RedisInstance};

src/redsync.rs

@@ -9,13 +9,15 @@ use std::time::{Duration, Instant};
 use rand::distributions::Alphanumeric;
 use rand::{thread_rng, Rng};
 
+/// `Lock` holds the metadata of an acquired lock.
 pub struct Lock {
     pub resource: String,
     pub value: String,
     pub ttl: Duration,
     pub expiry: Instant,
 }
 
+/// `Redsync` is a distributed lock manager that implements the Redlock algorithm.
 pub struct Redsync<I: Instance> {
     pub(crate) cluster: Vec<I>,
     pub(crate) quorum: u32,