📝 docs: start writing docs in `cargo doc` format

crates/always_equal/src/lib.rs

@@ -1,3 +1,56 @@
+//! # Always-Equal
+//! 
+//! Always-Equal lets you wrap `PartialEq` implementations around 
+//! things that cannot be compared, like a `File`.
+//! 
+//! To use Always-Equal, put these two conditional `use`
+//! statements in your module:
+//! 
+//! ```
+//! #[cfg (test)]
+//! use always_equal::test::AlwaysEqual;
+//! 
+//! #[cfg (not (test))]
+//! use always_equal::prod::AlwaysEqual;
+//! ```
+//! 
+//! Then wrap `AlwaysEqual` around anything that needs
+//! PartialEq but can't possibly implement it:
+//! 
+//! ```
+//! #[derive (Debug, PartialEq)]
+//! pub struct MyStruct {
+//! 	pub b: bool,
+//! 	pub i: i64,
+//! 	pub file: AlwaysEqual <File>,
+//! }
+//! ```
+//! 
+//! In test code, you can create an empty wrapper using
+//! `testing_blank`, which is equal to any other wrapper:
+//! 
+//! ```
+//! let expected = MyStruct {
+//! 	b: true,
+//! 	i: 0,
+//! 	file: AlwaysEqual::testing_blank (),
+//! };
+//! 
+//! let actual = MyStruct {
+//! 	b: true,
+//! 	i: 0,
+//! 	file: my_file.into (),
+//! };
+//! 
+//! assert_eq! (expected, actual);
+//! ```
+//! 
+//! This is implemented with `Option` in test mode.
+//! In production mode, wrappers are never equal to any other
+//! wrapper, and the `Option` is removed so that 
+//! `sizeof::<AlwaysEqual <T>> () == sizeof::<T>`
+//! _should_ be true.
+
 pub mod test {
 	#[derive (Debug)]
 	pub struct AlwaysEqual <T> {

src/lib.rs

@@ -1,2 +1,19 @@
+//! # PTTH
+//! 
+//! PTTH is a set of tools for running HTTP servers that are disguised
+//! as HTTP clients.
+//! 
+//! This crate only contains integration tests. The other crates
+//! fit into this dependency DAG:
+//! 
+//! ```
+//! * ptth
+//! |\
+//! | * ptth_server
+//! * | ptth_relay
+//! |/
+//! * ptth_core
+//! ```
+
 #[cfg (test)]
 mod tests;