add rustdoc for crates and readme

Signed-off-by: Bugen Zhao <[email protected]>

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "thiserror-ext"
-description = "Extensions to `thiserror`."
+description = "Useful extension utilities for `thiserror`."
 version = { workspace = true }
 edition = { workspace = true }
 authors = { workspace = true }

README.md

@@ -1,3 +1,50 @@
 # `thiserror-ext`
 
-Extensions to `thiserror`.
+[![Crate](https://img.shields.io/crates/v/thiserror-ext.svg)](https://crates.io/crates/thiserror-ext)
+[![Docs](https://docs.rs/thiserror-ext/badge.svg)](https://docs.rs/thiserror-ext)
+
+Useful extension utilities for `thiserror`. See the [documentation](https://docs.rs/thiserror-ext) for more details.
+
+```rust
+#[derive(
+    Debug,
+    thiserror::Error,
+    thiserror_ext::Box,
+    thiserror_ext::Construct,
+    thiserror_ext::ContextInto,
+    thiserror_ext::Macro,
+)]
+#[thiserror_ext(
+    newtype(name = Error, backtrace),
+    macro(path = "crate::foo"),
+)]
+enum ErrorKind {
+    #[error("cannot parse int from `{from}`")]
+    Parse {
+        source: std::num::ParseIntError,
+        from: String,
+    },
+
+    #[error("not yet implemented: {msg}")]
+    NotImplemented {
+        issue: Option<i32>,
+        #[message] msg: String,
+    }
+
+    #[error("internal error: {0}")]
+    Internal(String),
+}
+
+// `thiserror_ext::Box`
+assert_eq!(std::mem::size_of::<Error>(), std::mem::size_of::<usize>());
+let _: &Backtrace = std::error::request_ref(&error).unwrap();
+
+// `thiserror_ext::Construct`
+let _: Error = Error::internal("oops");
+
+// `thiserror_ext::ContextInto`
+let _: Result<i32, Error> = "foo".parse::<i32>().into_parse("foo");
+
+// `thiserror_ext::Macro`
+bail_not_implemented!(issue = 42, "an {} feature", "awesome");
+```

derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "thiserror-ext-derive"
-description = "Proc macros of `thiserror-ext`."
+description = "Procedural macros for `thiserror_ext`."
 version = { workspace = true }
 edition = { workspace = true }
 authors = { workspace = true }

derive/src/lib.rs

@@ -1,3 +1,5 @@
+//! Procedural macros for `thiserror_ext`.
+
 use expand::{DeriveCtorType, DeriveNewType};
 use proc_macro::TokenStream;
 use syn::{parse_macro_input, DeriveInput};

src/lib.rs

@@ -1,3 +1,22 @@
+//! Useful extension utilities for [`thiserror`].
+//!
+//! ## Painless construction
+//!
+//! With derive macros of [`Construct`], [`ContextInto`] and [`Macro`],
+//! one can construct an error in a much more convenient way, no matter it's
+//! from scratch or converted from other errors.
+//!
+//! ## Better formatting
+//!
+//! With extension [`AsReport`], one can format an error in a pretty and
+//! concise way, without losing any information from the error sources.
+//!
+//! ## Easier to interact with
+//!
+//! With derive macros of [`derive@Box`] and [`derive@Arc`], one can easily
+//! wrap an `enum` error type into a new type, reducing the size to improve
+//! performance, and automatically capturing backtraces if needed.
+
 #![feature(error_generic_member_access)] // TODO: it's nightly-only
 
 mod as_dyn;