📝 docs: finish some basic docs for always_equal

main
_ 2021-04-17 15:59:03 -05:00
parent e02dbf6e31
commit a911e53e48
1 changed files with 43 additions and 4 deletions

View File

@ -18,24 +18,26 @@
//! PartialEq but can't possibly implement it: //! PartialEq but can't possibly implement it:
//! //!
//! ``` //! ```
//! use std::fs::File;
//! use always_equal::test::AlwaysEqual;
//!
//! #[derive (Debug, PartialEq)] //! #[derive (Debug, PartialEq)]
//! pub struct MyStruct { //! pub struct MyStruct {
//! pub b: bool, //! pub b: bool,
//! pub i: i64, //! pub i: i64,
//! pub file: AlwaysEqual <File>, //! 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 { //! let expected = MyStruct {
//! b: true, //! b: true,
//! i: 0, //! i: 0,
//! file: AlwaysEqual::testing_blank (), //! file: AlwaysEqual::testing_blank (),
//! }; //! };
//! //!
//! # let my_file = File::open ("Cargo.toml").unwrap ();
//! let actual = MyStruct { //! let actual = MyStruct {
//! b: true, //! b: true,
//! i: 0, //! i: 0,
@ -51,9 +53,27 @@
//! `sizeof::<AlwaysEqual <T>> () == sizeof::<T>` //! `sizeof::<AlwaysEqual <T>> () == sizeof::<T>`
//! _should_ be true. //! _should_ be true.
/// Should be used for non-test builds
pub mod prod { pub mod prod {
use std::fmt; 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> { pub struct AlwaysEqual <T> {
inner: T, inner: T,
} }
@ -91,7 +111,26 @@ pub mod prod {
} }
} }
/// Should be used for test builds
pub mod test { 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)] #[derive (Debug)]
pub struct AlwaysEqual <T> { pub struct AlwaysEqual <T> {
inner: Option <T>, inner: Option <T>,