📝 docs: finish some basic docs for always_equal

crates/always_equal/src/lib.rs

@@ -18,24 +18,26 @@
 //! PartialEq but can't possibly implement it:
 //! 
 //! ```
+//! use std::fs::File;
+//! use always_equal::test::AlwaysEqual;
+//! 
 //! #[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
+//! // In test code, you can create an empty wrapper using
-//! `testing_blank`, which is equal to any other wrapper:
+//! // `testing_blank`, which is equal to any other wrapper:
 //! 
-//! ```
 //! let expected = MyStruct {
 //! 	b: true,
 //! 	i: 0,
 //! 	file: AlwaysEqual::testing_blank (),
 //! };
 //! 
+//! # let my_file = File::open ("Cargo.toml").unwrap ();
 //! let actual = MyStruct {
 //! 	b: true,
 //! 	i: 0,
@@ -51,9 +53,27 @@
 //! `sizeof::<AlwaysEqual <T>> () == sizeof::<T>`
 //! _should_ be true.
 
+/// Should be used for non-test builds
+
 pub mod prod {
 	use std::fmt;
 	
+	/// In prod mode, `AlwaysEqual <T>` has the same size as `T`.
+	/// `Debug` and `Display` are passed through if `T` implements
+	/// them. `PartialEq` always returns `false` in prod mode.
+	/// 
+	/// Wrapping a string, checking its equality, and unwrapping it:
+	/// 
+	/// ```
+	/// use always_equal::prod::AlwaysEqual;
+	/// 
+	/// let s = "some string";
+	/// let a = AlwaysEqual::from (s);
+	/// let b = AlwaysEqual::from (s);
+	/// assert_ne! (a, b);
+	/// let s2 = a.into_inner ();
+	/// ```
+	
 	pub struct AlwaysEqual <T> {
 		inner: T,
 	}
@@ -91,7 +111,26 @@ pub mod prod {
 	}
 }
 
+/// Should be used for test builds
+
 pub mod test {
+	/// In test mode, `AlwaysEqual <T>` has the same size as
+	/// `Option <T>`. `Debug` is derived. `PartialEq` returns
+	/// `true` if either operand is a testing blank.
+	/// 
+	/// Wrapping a string, comparing it with a testing blank,
+	/// and unwrapping it:
+	/// 
+	/// ```
+	/// use always_equal::test::AlwaysEqual;
+	/// 
+	/// let s = "some string";
+	/// let a = AlwaysEqual::from (s);
+	/// let b = AlwaysEqual::testing_blank ();
+	/// assert_eq! (a, b);
+	/// let s2 = a.into_inner ();
+	/// ```
+	
 	#[derive (Debug)]
 	pub struct AlwaysEqual <T> {
 		inner: Option <T>,