Add readme docs to lib

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "eyre"
-version = "0.3.4" # remember to update html_root_url
+version = "0.3.5" # remember to update html_root_url
 authors = ["David Tolnay <dtolnay@gmail.com>", "Jane Lusby <jlusby42@gmail.com>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"

src/lib.rs

@@ -1,6 +1,137 @@
 //! This library provides [`eyre::ErrReport`][ErrReport], a trait object based error
 //! type for easy idiomatic error handling in Rust applications.
 //!
+//! This crate is a fork of [`anyhow`] by @dtolnay. By default this crate does not
+//! add any new features that anyhow doesn't already support, though it does rename
+//! a number of the APIs to try to make the proper usage more obvious. The magic of
+//! this crate is when you need to add extra context to a chain of errors beyond
+//! what you can or should insert into the error chain. For an example of a
+//! customized version of eyre check out
+//! [`jane-eyre`](https://github.com/yaahc/jane-eyre).
+//!
+//! My goal in writing this crate is to explore new ways to associate context with
+//! errors, to cleanly separate the concept of an error and context about an error,
+//! and to more clearly communicate the intended usage of this crate via changes to
+//! the API.
+//!
+//! The main changes this crate brings to anyhow are
+//!
+//! * Addition of the [`eyre::EyreContext`] trait and a type parameter on the core
+//!   error handling type which users can use to insert custom forms of context
+//!   into their catch-all error handling type.
+//! * Rebranding the type as principally for error reporting, rather than
+//!   describing it as an error type in its own right. What is and isn't an error
+//!   is a fuzzy concept, for the purposes of this crate though errors are types
+//!   that implement `std::error::Error`, and you'll notice that this trait
+//!   implementation is conspicuously absent on `ErrReport`. Instead it contains
+//!   errors that it masqerades as, and provides helpers for creating new errors to
+//!   wrap those errors and for displaying those chains of errors, and the included
+//!   context, to the end user. The goal is to make it obvious that this type is
+//!   meant to be used when the only way you expect to handle errors is to print
+//!   them.
+//! * Changing the [`anyhow::Context`] trait to [`eyre::WrapErr`] to make it clear
+//!   that it is unrelated to the [`eyre::EyreContext`] trait and member, and is
+//!   only for inserting new errors into the chain of errors.
+//! * Addition of new context helpers on `EyreContext` (`member_ref`/`member_mut`)
+//!   and `context`/`context_mut` on `ErrReport` for working with the custom
+//!   context and extracting forms of context based on their type independent of
+//!   the type of the custom context.
+//!
+//! These changes were made in order to facilitate the usage of
+//! [`tracing_error::SpanTrace`] with anyhow, which is a Backtrace-like type for
+//! rendering custom defined runtime context.
+//!
+//! ```toml
+//! [dependencies]
+//! eyre = "0.3"
+//! ```
+//! <br>
+//!
+//! ## Customization
+//!
+//! In order to insert your own custom context type you must first implement the
+//! `eyre::EyreContext` trait for said type, which has three required methods and
+//! two optional methods.
+//!
+//! ### Required Methods
+//!
+//! * `fn default(error: &Error) -> Self` - For constructing default context while
+//! allowing special case handling depending on the content of the error you're
+//! wrapping.
+//!
+//! This is essentially `Default::default` but more flexible, for example, the
+//! `eyre::DefaultContext` type provide by this crate uses this to only capture a
+//! `Backtrace` if the inner `Error` does not already have one.
+//!
+//! ```rust,compile_fail
+//! fn default(error: &(dyn StdError + 'static)) -> Self {
+//!     let backtrace = backtrace_if_absent!(error);
+//!
+//!     Self { backtrace }
+//! }
+//! ```
+//!
+//! * `fn debug(&self, error: &(dyn Error + 'static), f: &mut fmt::Formatter<'_>) -> fmt Result`
+//!   it's companion `display` version. - For formatting the entire error chain and
+//!   the user provided context.
+//!
+//! When overriding the context it no longer makes sense for `eyre::ErrReport` to
+//! provide the `Display` and `Debug` implementations for the user, becase we
+//! cannot predict what forms of context you will need to display along side your
+//! chain of errors. Instead we forward the implementations of `Display` and
+//! `Debug` to these methods on the inner `EyreContext` type.
+//!
+//! This crate does provide a few helpers to assist in writing display
+//! implementations, specifically the `Chain` type, for treating an error and its
+//! sources like an iterator, and the `Indented` type, for indenting multi line
+//! errors consistently without using heap allocations.
+//!
+//! **Note**: best practices for printing errors suggest that `{}` should only
+//! print the current error and none of its sources, and that the primary method of
+//! displaying an error, its sources, and its context should be handled by the
+//! `Debug` implementation, which is what is used to print errors that are returned
+//! from `main`. For examples on how to implement this please refer to the
+//! implementations of `display` and `debug` on `eyre::DefaultContext`
+//!
+//! ### Optional Methods
+//!
+//! * `fn member_ref(&self, typeid TypeID) -> Option<&dyn Any>` - For extracting
+//!   arbitrary members from a context based on their type and `member_mut` for
+//!   getting a mutable reference in the same way.
+//!
+//! This method is like a flexible version of the `fn backtrace(&self)` method on
+//! the `Error` trait. The main `ErrReport` type provides versions of these methods
+//! that use type inference to get the typeID that should be used by inner trait fn
+//! to pick a member to return.
+//!
+//! **Note**: The `backtrace()` fn on `ErrReport` relies on the implementation of
+//! this function to get the backtrace from the user provided context if one
+//! exists. If you wish your type to guaruntee that it captures a backtrace for any
+//! error it wraps you **must** implement `member_ref` and provide a path to return
+//! a `Backtrace` type like below.
+//!
+//! Here is how the `eyre::DefaultContext` type uses this to return `Backtrace`s.
+//!
+//! ```rust,compile_fail
+//! fn member_ref(&self, typeid: TypeId) -> Option<&dyn Any> {
+//!     if typeid == TypeId::of::<Backtrace>() {
+//!         self.backtrace.as_ref().map(|b| b as &dyn Any)
+//!     } else {
+//!         None
+//!     }
+//! }
+//! ```
+//!
+//! Once you've defined a custom Context type you can use it throughout your
+//! application by defining a type alias.
+//!
+//!
+//! ```rust,compile_fail
+//! type ErrReport = eyre::ErrReport<MyContext>;
+//!
+//! // And optionally...
+//! type Result<T, E = eyre::ErrReport<MyContext>> = core::result::Result<T, E>;
+//! ```
 //! <br>
 //!
 //! # Details
@@ -176,7 +307,7 @@
 //! will require an explicit `.map_err(ErrReport::msg)` when working with a
 //! non-Eyre error type inside a function that returns Eyre's error type.
 
-#![doc(html_root_url = "https://docs.rs/eyre/0.3.4")]
+#![doc(html_root_url = "https://docs.rs/eyre/0.3.5")]
 #![cfg_attr(backtrace, feature(backtrace))]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(