From b76bff9b886003a6819948126844ae73c583cb06 Mon Sep 17 00:00:00 2001
From: Sarthak <sarthak.makhija@gmail.com>
Date: Thu, 18 Jan 2024 14:03:10 +0530
Subject: [PATCH] Sarthak | Adds documentation for SomePredicateAssertion,
 OkPredicateAssertion and their matchers

---
 src/assertions/option/predicate.rs | 21 +++++++++++++++++++++
 src/assertions/result/predicate.rs | 21 +++++++++++++++++++++
 src/matchers/option/predicate.rs   | 11 +++++++++++
 src/matchers/result/predicate.rs   | 13 +++++++++++++
 4 files changed, 66 insertions(+)

diff --git a/src/assertions/option/predicate.rs b/src/assertions/option/predicate.rs
index c92c012..7ecf964 100644
--- a/src/assertions/option/predicate.rs
+++ b/src/assertions/option/predicate.rs
@@ -2,9 +2,30 @@ use crate::matchers::{Should, ShouldNot};
 use crate::matchers::option::be_some;
 use crate::matchers::option::predicate::satisfy;
 
+/// SomePredicateAssertion enables assertions about whether the Option value is both Some and that the contained value meets or doesn't meet certain conditions defined by a predicate.
 pub trait SomePredicateAssertion<T> {
+    /// - Asserts that the Option value is Some and satisfies the given predicate.
+    /// - Returns a reference to self for fluent chaining.
+    /// - Panics if the assertion fails.
+    /// # Example
+    /// ```
+    /// use clearcheck::assertions::option::predicate::SomePredicateAssertion;
+    ///
+    /// let option = Some(100);
+    /// option.should_be_some_and_satisfy(|value| value > &&50);
+    /// ```
     fn should_be_some_and_satisfy<F: Fn(&&T) -> bool>(&self, predicate: F) -> &Self;
 
+    /// - Asserts that the Option value is Some and does not satisfy the given predicate.
+    /// - Returns a reference to self for fluent chaining.
+    /// - Panics if the assertion fails.
+    /// # Example
+    /// ```
+    /// use clearcheck::assertions::option::predicate::SomePredicateAssertion;
+    ///
+    /// let option = Some(100);
+    /// option.should_be_some_and_not_satisfy(|value| value > &&500);
+    /// ```
     fn should_be_some_and_not_satisfy<F: Fn(&&T) -> bool>(&self, predicate: F) -> &Self;
 }
 
diff --git a/src/assertions/result/predicate.rs b/src/assertions/result/predicate.rs
index 9e3da42..d86b16c 100644
--- a/src/assertions/result/predicate.rs
+++ b/src/assertions/result/predicate.rs
@@ -2,9 +2,30 @@ use crate::matchers::{Should, ShouldNot};
 use crate::matchers::result::predicate::satisfy;
 use crate::matchers::result::be_ok;
 
+/// OkPredicateAssertion enables assertions about whether the Result value is both Ok and that the contained value meets or doesn't meet certain conditions defined by a predicate.
 pub trait OkPredicateAssertion<T> {
+    /// - Asserts that the Result value is Ok and satisfies the given predicate.
+    /// - Returns a reference to self for fluent chaining.
+    /// - Panics if the assertion fails.
+    /// # Example
+    /// ```
+    /// use clearcheck::assertions::result::predicate::OkPredicateAssertion;
+    ///
+    /// let value: Result<i32, &str> = Ok(1000);
+    /// value.should_be_ok_and_satisfy(|value| value > &50);
+    /// ```
     fn should_be_ok_and_satisfy<F: Fn(&T) -> bool>(&self, predicate: F) -> &Self;
 
+    /// - Asserts that the Result value is Ok and does not satisfy the given predicate.
+    /// - Returns a reference to self for fluent chaining.
+    /// - Panics if the assertion fails.
+    /// # Example
+    /// ```
+    /// use clearcheck::assertions::result::predicate::OkPredicateAssertion;
+    ///
+    /// let value: Result<i32, &str> = Ok(100);
+    /// value.should_be_ok_and_not_satisfy(|value| value > &500);
+    /// ```
     fn should_be_ok_and_not_satisfy<F: Fn(&T) -> bool>(&self, predicate: F) -> &Self;
 }
 
diff --git a/src/matchers/option/predicate.rs b/src/matchers/option/predicate.rs
index d2d8835..c101c1e 100644
--- a/src/matchers/option/predicate.rs
+++ b/src/matchers/option/predicate.rs
@@ -2,6 +2,16 @@ use std::marker::PhantomData;
 
 use crate::matchers::{Matcher, MatcherResult};
 
+/// SomePredicateMatcher offers a flexible way to assert whether the Option value is both Some and that the contained value meets certain conditions defined by the predicate.
+///
+/// # Example
+///```
+/// use clearcheck::matchers::Matcher;
+/// use clearcheck::matchers::option::predicate::satisfy;
+///
+/// let matcher = satisfy(|value| value > &&400);
+/// assert!(matcher.test(&Some(1000)).passed());
+/// ```
 pub struct SomePredicateMatcher<F, T>
     where F: Fn(&&T) -> bool
 {
@@ -21,6 +31,7 @@ impl<F, T> Matcher<Option<T>> for SomePredicateMatcher<F, T>
     }
 }
 
+/// Creates a SomePredicateMatcher that asserts whether the Option value is both Some and that the contained value meets certain conditions defined by the predicate.
 pub fn satisfy<F, T>(predicate: F) -> SomePredicateMatcher<F, T>
     where F: Fn(&&T) -> bool
 {
diff --git a/src/matchers/result/predicate.rs b/src/matchers/result/predicate.rs
index cbbd229..3099386 100644
--- a/src/matchers/result/predicate.rs
+++ b/src/matchers/result/predicate.rs
@@ -1,6 +1,18 @@
 use std::marker::PhantomData;
 use crate::matchers::{Matcher, MatcherResult};
 
+/// OkPredicateMatcher offers a flexible way to assert whether the Result value is both Ok and that the contained value meets certain conditions defined by the predicate.
+///
+/// # Example
+///```
+/// use clearcheck::matchers::Matcher;
+/// use clearcheck::matchers::result::predicate::satisfy;
+///
+/// let matcher = satisfy(|value| value > &400);
+/// let value: Result<i32, &str> = Ok(1000);
+///
+/// assert!(matcher.test(&value).passed());
+/// ```
 pub struct OkPredicateMatcher<F, T>
     where F: Fn(&T) -> bool
 {
@@ -20,6 +32,7 @@ impl<F, T, E> Matcher<Result<T, E>> for OkPredicateMatcher<F, T>
     }
 }
 
+/// Creates an OkPredicateMatcher that asserts whether the Result value is both Ok and that the contained value meets certain conditions defined by the predicate.
 pub fn satisfy<F, T>(predicate: F) -> OkPredicateMatcher<F, T>
     where F: Fn(&T) -> bool
 {