doc: mention field-by-field recursive comparison in the crate level documentation

Author: haraldmaida

src/lib.rs

@@ -5,7 +5,7 @@
 //! particularly as provided by this crate:
 //!
 //! * express the intent of an assertion
-//! * an assertion reads more like natural english
+//! * an assertion reads more like natural English
 //! * concise and expressive assertions for more complex types like collections
 //! * distinct and more helpful error messages for specific assertions
 //! * easy spotting the difference between the expected and the actual value
@@ -320,6 +320,85 @@
 //! # }
 //! ```
 //!
+//! ## Field-by-field recursive comparison
+//!
+//! Requires crate feature `recursive`.
+//!
+//! The recursive comparison mode compares the subject and the expected value
+//! field-by-field recursively. The recursive comparison mode is available for
+//! all types that implement [`serde::Serialize`].
+//!
+//! Basic usage:
+//!
+//! ```
+//! # #[cfg(not(feature = "recursive"))]
+//! # fn main() {}
+//! # #[cfg(feature = "recursive")]
+//! # fn main() {
+//! use asserting::prelude::*;
+//! use serde::Serialize;
+//!
+//! #[derive(Serialize)]
+//! struct Address {
+//!     id: u64,
+//!     street: String,
+//!     city: String,
+//!     zip: u16,
+//! }
+//!
+//! #[derive(Serialize)]
+//! struct Person {
+//!     id: u64,
+//!     name: String,
+//!     age: u8,
+//!     address: Address,
+//! }
+//!
+//! let person = Person {
+//!     id: 123,
+//!     name: "Silvia".into(),
+//!     age: 25,
+//!     address: Address {
+//!         id: 92,
+//!         street: "Second Street".into(),
+//!         city: "New York".into(),
+//!         zip: 12345,
+//!     }
+//! };
+//!
+//! // ignore some fields
+//! assert_that!(&person)
+//!     .using_recursive_comparison()
+//!     .ignoring_fields(["id", "address.id", "address.street"])
+//!     .is_equal_to(Person {
+//!         id: 0,
+//!         name: "Silvia".into(),
+//!         age: 25,
+//!         address: Address {
+//!             id: 0,
+//!             street: "Main Street".into(),
+//!             city: "New York".into(),
+//!             zip: 12345,
+//!         }
+//!     });
+//!
+//! // assert only fields relevant for a testcase
+//! assert_that!(person)
+//!     .using_recursive_comparison()
+//!     .ignoring_not_expected_fields()
+//!     .is_equivalent_to(value!({
+//!         name: "Silvia",
+//!         age: 25_u8,
+//!         address: {
+//!             zip: 12345_u16,
+//!         }
+//!     }));
+//! # }
+//! ```
+//!
+//! A more in-depth description of the recursive comparison mode is given in the
+//! [`recursive_comparison`] module.
+//!
 //! # The `assert_that` and `verify_that` functions and macros
 //!
 //! Assertions can be written in two ways. The standard way that panics when
@@ -341,7 +420,7 @@
 //!   failures from assertions, which can be read later.
 //!
 //! The [`Spec`] can hold additional information about the subject, such as the
-//! expression we are asserting, the code location of the assert statement and
+//! expression we are asserting, the code location of the assert statement, and
 //! an optional description of what we are going to assert. These attributes are
 //! all optional and must be set explicitly by the user.
 //!
@@ -760,6 +839,7 @@
 //! [`failures()`]: spec::GetFailures::failures
 //! [`named()`]: spec::Spec::named
 //! [`located_at()`]: spec::Spec::located_at
+//! [`serde::Serialize`]: serde_core::Serialize
 
 #![doc(html_root_url = "https://docs.rs/asserting/0.13.1")]
 #![cfg_attr(not(feature = "std"), no_std)]

src/recursive_comparison/mod.rs

@@ -8,25 +8,25 @@
 //! There are several scenarios where recursive comparison is useful:
 //!
 //! * comparing types that have similar fields, like an entity and a DTO
-//!   representation of the same type in the application's domain.
+//!   representation of the same thing in the application's domain.
 //! * comparing only fields that are relevant for a specific test case and
 //!   ignoring others.
 //! * comparing types field-by-field but ignoring fields, where the actual value
 //!   may vary like for IDs or timestamps.
 //! * comparing types that implement `Serialize` but not `PartialEq` or `Debug`
 //!
-//! Recursive comparison provides detailed failure messages in case of a failing
+//! Recursive comparison provides detailed failure reports in case of a failing
 //! assertion. The failure details contain a list of fields, for which the
 //! actual value is not equal to the expected one. This is another reason why
 //! recursive comparison might be the preferred way, especially when comparing
-//! structs that have many fields and/or contain sub-structs.
+//! structs that have many fields and/or contain nested structs.
 //!
-//! Recursive comparison is started by calling the `using_recursive_comparison`
-//! method.
+//! The recursive comparison mode starts after calling the
+//! `using_recursive_comparison` method.
 //!
 //! Recursive comparison is not symmetrical since it is limited to the fields
 //! of the subject (actual value). It gathers the actual fields of the subject
-//! and compares them to the corresponding fields haven the same name in the
+//! and compares them to the corresponding fields having the same name in the
 //! expected value.
 //!
 //! Structs, enums, and tuples in the subject and expected value do not
@@ -37,9 +37,16 @@
 //! value is only equal to the expected field if the names and values are equal
 //! and the expected value is of type `u8` too.
 //!
-//! The recursive comparison is limited down to a max depth of 128 levels,
+//! Recursive comparison is limited down to a max depth of 128 levels,
 //! which is the default max depth of [`serde::Serialize`].
 //!
+//! The recursive comparison mode provides the following capabilities:
+//!
+//! * [Ignoring fields in the comparison](#ignoring-some-fields)
+//! * [Comparing only specified fields](RecursiveComparison::comparing_only_fields)
+//! * [Ignoring all fields that are not present in the expected value](#ignoring-not-expected-fields)
+//! * [Comparing only relevant fields](#comparing-only-relevant-fields)
+//!
 //! # Examples
 //!
 //! ## Comparing structs with several fields and nested structs