Improve documentation for crate

Author: Daniel Lyne

README.md

@@ -24,7 +24,7 @@ While the exact configuration will depend on the backend used, usage is roughly
    If you only need some backends, then simply disable the default features, and enable any backends
    that you require.
 
-2. Construct anud use your queue.
+2. Construct and use your queue.
 
    The exact configuration type used will depend on your backend, but it's as simple as:
 
@@ -89,7 +89,7 @@ let (p, mut c) = RabbitMqBackend::builder(cfg)
 	})
 	.with_decoder(|v: &Vec<u8>| -> Result<ExampleType, QueueError> {
 		Ok(ExampleType {
-			field: *v.first().unwrap_or(i&0),
+			field: *v.first().unwrap_or(&0),
 		})
 	})
 	.build_pair()

omniqueue/src/lib.rs

@@ -1,3 +1,104 @@
+//! # Omniqueue
+//!
+//! Omniqueue is an abstraction layer over various queue backends. As of present it supports:
+//!
+//!   * In-memory queues
+//!
+//!   * RabbitMQ
+//!
+//!   * Redis streams
+//!
+//!   * SQS
+//!
+//! Omniqueue provides a high-level interface for sending and receiving
+//!
+//!   * Raw byte arrays in the way most compatible with the queue backend
+//!
+//!   * JSON encoded byte arrays for types that implement [`serde::Deserialize`] and
+//!     [`serde::Serialize`]
+//!
+//!   * Arbitrary types for which an encoder and/or decoder has been defined
+//!
+//! ## How to Use Omniqueue
+//!
+//!   1. Start by adding `omniqueue` to your `Cargo.toml`. If you don't need support for all of the
+//!      backends, disable the default features and enable each required backend individually.
+//!
+//!   2. Create the configuration for your queue backend. Depending on which backend you use, this
+//!      could be [`backends::rabbitmq::RabbitMqConfig`], [`backends::redis::RedisConfig`],
+//!      [`backends::sqs::SqsConfig`], or a simple [`usize`] for memory queues.
+//!
+//!   3. Create the producer and/or consumer:
+//!
+//!      ```compile_fail
+//!      use omniqueue::backends::sqs::{SqsConfig, SqsQueueBackend};
+//!      use
+//!
+//!      let cfg = SqsConfig {
+//!          queue_dsn: "http://localhost:9234/queue/queue_name".to_owned(),
+//!          override_endpoint: true,
+//!      };
+//!      
+//!      // Either both producer and consumer
+//!      let (p, mut c) = SqsQueueBackend::builder(cfg.clone()).build_pair().await?;
+//!
+//!      // Or one half
+//!      let p = SqsQueueBackend::builder(cfg.clone()).build_producer().await?;
+//!      let mut c = SqsQueueBackend::builder(cfg).build_consumer().await?;
+//!
+//!      (p, c)
+//!      ```
+//!
+//!   4. Send and receive information:
+//!
+//!      ```compile_fail
+//!      p.send_serde_json(&ExampleType::default()).await?;
+//!
+//!      let delivery = c.receive().await?;
+//!      let payload = delivery.payload_serde_json::<ExampleType>().await?;
+//!      delivery.ack().await?;
+//!      ```
+//! ## `DynProducer`s and `DynConsumer`s
+//!
+//! Dynamic-dispatch can be used easily for when you're not sure which backend is to be used at
+//! compile-time.
+//!
+//! Making a `DynProducer` or `DynConsumer` is as simple as adding one line to the builder:
+//!
+//! ```compile_fail
+//! let (p, mut c) = RabbitMqBackend::builder(cfg)
+//!     .make_dynamic()
+//!     .build_pair()
+//!     .await?;
+//! ```
+//!
+//! ## Encoders/Decoders
+//!
+//! The [`encoding::CustomEncoder`]s and [`decoding::CustomDecoder`]s given to the builder upon
+//! producer/consumer creation will be used to convert from/to the queue's native representation
+//! into/from a given type. This helps enforce a separation of responsibilities where only the
+//! application setting up a concrete queue instance should ever have to think about the internal
+//! data-representation of items within the queue while abstract uses of queues should be able to
+//! work with simple Rust types.
+//!
+//! Any function or closure with the right signature may be used as an encoder or decoder.
+//!
+//! ```compile_fail
+//! #[derive(Debug, PartialEq)]
+//! struct ExampleType {
+//!     field: u8,
+//! }
+//!
+//! let (p, mut c) = RabbitMqBackend::builder(cfg)
+//!     .with_encoder(|et: &ExampleType| -> Result<Vec<u8>, QueueError> {
+//!         Ok(vec![et.field])
+//!     })
+//!     .with_decoder(|v: &Vec<u8>| -> Result<ExampleType, QueueError> {
+//!         Ok(ExampleType {
+//!             field: *v.first().unwrap_or(&0),
+//!         })
+//!     })
+//! ```
 use std::fmt::Debug;
 
 use thiserror::Error;