From 208cb84f69c438d70f32488daeffff90655146ec Mon Sep 17 00:00:00 2001
From: Jane Lusby <jlusby@yaah.dev>
Date: Wed, 6 May 2020 15:51:03 -0700
Subject: [PATCH] final prep before release

---
 README.md  |  5 ++++-
 src/lib.rs | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cde1512..9a913c8 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ of [`color-backtrace`].
 
 Add the following to your `Cargo.toml`:
 
-```
+```toml
 [dependencies]
 color-spantrace = "0.1"
 tracing = "0.1.13"
@@ -47,6 +47,9 @@ fn foo() -> SpanTrace {
 And finally colorize the `SpanTrace`:
 
 ```rust
+use tracing_error::SpanTrace;
+
+let span_trace = SpanTrace::capture();
 println!("{}", color_spantrace::colorize(&span_trace));
 ```
 
diff --git a/src/lib.rs b/src/lib.rs
index 5103e65..a045649 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,50 @@
+//! A rust library for colorizing [`tracing_error::SpanTrace`] objects in the style
+//! of [`color-backtrace`].
+//!
+//! ## Setup
+//!
+//! Add the following to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! color-spantrace = "0.1"
+//! tracing = "0.1.13"
+//! tracing-error = "0.1.2"
+//! tracing-subscriber = "0.2.5"
+//! ```
+//!
+//! Setup a tracing subscriber with an `ErrorLayer`:
+//!
+//! ```rust
+//! use tracing_error::ErrorLayer;
+//! use tracing_subscriber::{prelude::*, registry::Registry};
+//!
+//! Registry::default().with(ErrorLayer::default()).init();
+//! ```
+//!
+//! Create spans and enter them:
+//!
+//! ```rust
+//! use tracing::instrument;
+//! use tracing_error::SpanTrace;
+//!
+//! #[instrument]
+//! fn foo() -> SpanTrace {
+//!     SpanTrace::capture()
+//! }
+//! ```
+//!
+//! And finally colorize the `SpanTrace`:
+//!
+//! ```rust
+//! use tracing_error::SpanTrace;
+//!
+//! let span_trace = SpanTrace::capture();
+//! println!("{}", color_spantrace::colorize(&span_trace));
+//! ```
+//!
+//! [`tracing_error::SpanTrace`]: https://docs.rs/tracing-error/*/tracing_error/struct.SpanTrace.html
+//! [`color-backtrace`]: https://github.com/athre0z/color-backtrace
 #![doc(html_root_url = "https://docs.rs/color-spantrace/0.1.0")]
 use ansi_term::{Color::*, Style};
 use std::env;
@@ -7,6 +54,21 @@ use std::io::{BufRead, BufReader, ErrorKind};
 use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
 use tracing_error::SpanTrace;
 
+/// Display a [`SpanTrace`] with colors and source
+///
+/// This function returns an `impl Display` type which can be then used in place of the original
+/// SpanTrace when writing it too the screen or buffer.
+///
+/// # Example
+///
+/// ```rust
+/// use tracing_error::SpanTrace;
+///
+/// let span_trace = SpanTrace::capture();
+/// println!("{}", color_spantrace::colorize(&span_trace));
+/// ```
+///
+/// [`SpanTrace`]: https://docs.rs/tracing-error/*/tracing_error/struct.SpanTrace.html
 pub fn colorize(span_trace: &SpanTrace) -> impl fmt::Display + '_ {
     ColorSpanTrace { span_trace }
 }