docs: added rustdoc with examples and panic sections to all structs a…

…nd functions

.gitignore

@@ -1,2 +1,3 @@
 /target
 /Cargo.lock
+.idea

README.md

@@ -56,4 +56,4 @@ assert_that(result)
 - `is` to assert equality in a type safe way (compared to the `Into<T>` stuff)
 - vec support (length, contains)
 - string support (length, contains, starts_with, ends_with)
-- Documentation and testing :D (especially the differnence between `is` and `equals`)
+- Documentation and testing :D (especially the difference between `is` and `equals`)

src/basic/equals.rs

@@ -4,7 +4,21 @@ impl<AssertedType> AssertionBuilder<AssertedType>
 where
     AssertedType: PartialEq + std::fmt::Debug,
 {
-    // FIXME: the type inference is bad as i32 does not implement Into<u16>
+    // FIXME: the type inference for {integers} is bad as i32 does not implement Into<u16>
+    /// Asserts that the assertable is equal to the expected value.
+    ///
+    /// This is done by transforming the expected-value to a instance of `AssertedType` by using the [Into]-trait
+    /// and then comparing both values with [`PartialEq`]
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// assert_that(String::from("Hello World!")).equals("Hello World!");
+    /// ```
+    ///
+    /// # Panics
+    /// When the values are not matching according to [`PartialEq`]
     pub fn equals(self, expected: impl Into<AssertedType>) {
         let expected: AssertedType = expected.into();
         implementation::assert_equals(self.value, expected);

src/basic/not_equals.rs

@@ -4,7 +4,21 @@ impl<AssertedType> AssertionBuilder<AssertedType>
 where
     AssertedType: PartialEq + std::fmt::Debug,
 {
-    // FIXME: the type inference is bad as i32 does not implement Into<u16>
+    // FIXME: the type inference for {integers} is bad as i32 does not implement Into<u16>
+    /// Asserts that the assertable is *not* equal to the expected value.
+    ///
+    /// This is done by transforming the expected-value to a instance of `AssertedType` by using the [Into]-trait
+    /// and then comparing both values with [`PartialEq`]
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// assert_that(String::from("Hello World!")).not_equals("Hello There!");
+    /// ```
+    ///
+    /// # Panics
+    /// When the values are matching according to [`PartialEq`]
     pub fn not_equals(self, expected: impl Into<AssertedType>) {
         let expected: AssertedType = expected.into();
         implementation::assert_not_equals(self.value, expected);

src/basic/try_equals.rs

@@ -4,11 +4,26 @@ impl<AssertedType> AssertionBuilder<AssertedType>
 where
     AssertedType: PartialEq + std::fmt::Debug,
 {
+    /// Asserts that the assertable is equal to the expected value.
+    ///
+    /// This is done by transforming the expected-value to a instance of `AssertedType` by using the [`TryInto`]-trait
+    /// and then comparing both values with [`PartialEq`]
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// assert_that(42u8).try_into_equals(42i8);
+    /// ```
+    ///
+    /// # Panics
+    /// When the transformation fails or the values are not matching according to [`PartialEq`]
     pub fn try_into_equals<T>(self, expected: T)
     where
         T: TryInto<AssertedType>,
         <T as TryInto<AssertedType>>::Error: std::fmt::Debug,
     {
+        // TODO: improve assertion here
         let expected: AssertedType = expected.try_into().unwrap();
         implementation::assert_equals(self.value, expected);
     }

src/basic/try_not_equals.rs

@@ -4,11 +4,26 @@ impl<AssertedType> AssertionBuilder<AssertedType>
 where
     AssertedType: PartialEq + std::fmt::Debug,
 {
+    /// Asserts that the assertable is *not* equal to the expected value.
+    ///
+    /// This is done by transforming the expected-value to a instance of `AssertedType` by using the [`TryInto`]-trait
+    /// and then comparing both values with [`PartialEq`]
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// assert_that(42u8).try_into_not_equals(100i8);
+    /// ```
+    ///
+    /// # Panics
+    /// When the transformation fails or the values are matching according to [`PartialEq`]
     pub fn try_into_not_equals<T>(self, expected: T)
     where
         T: TryInto<AssertedType>,
         <T as TryInto<AssertedType>>::Error: std::fmt::Debug,
     {
+        // TODO: improve assertion here
         let expected: AssertedType = expected.try_into().unwrap();
         implementation::assert_not_equals(self.value, expected);
     }

src/lib.rs

@@ -2,7 +2,7 @@
 //!
 //! # Examples
 //!
-//! All asserted are stared by calling [assert_that] on a value.
+//! All asserted are stared by calling [`assert_that`] on a value.
 //! After that various assertions based on the type of the asserted value can be made.
 //!
 //! ## Basic value assertions
@@ -11,7 +11,7 @@
 //!
 //! ### Equality
 //!
-//! [equals](struct.AssertionBuilder.html#method.equals) and [not_equals](struct.AssertionBuilder.html#method.not_equals) take anything that can be converted to the asserted type to improve ergonimics.  
+//! [`equals`](struct.AssertionBuilder.html#method.equals) and [`not_equals`](struct.AssertionBuilder.html#method.not_equals) take anything that can be converted to the asserted type to improve ergonimics.  
 //! This is done by implementing the [Into] trait.
 //!
 //! ```
@@ -26,7 +26,7 @@
 //! assert_that(String::from("Hello")).not_equals("Hello There");
 //! ```
 //!
-//! Same for [try_into_equals](struct.AssertionBuilder.html#method.try_into_equals) and [try_into_not_equals](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [TryInto] is used.
+//! Same for [`try_into_equals`](struct.AssertionBuilder.html#method.try_into_equals) and [`try_into_not_equals`](struct.AssertionBuilder.html#method.try_into_not_equals) but here the trait [`TryInto`] is used.
 //!
 //! ```
 //! # use smoothy::assert_that;
@@ -40,8 +40,8 @@
 //!
 //! ## Results
 //!
-//! Results can be asserted by calling [is_err](struct.AssertionBuilder.html#method.is_err) or [is_ok](struct.AssertionBuilder.html#method.is_ok).
-//! Futhermore their actual content can be asserted aswell.
+//! Results can be asserted by calling [`is_err`](struct.AssertionBuilder.html#method.is_err) or [`is_ok`](struct.AssertionBuilder.html#method.is_ok).
+//! Furthermore their actual content can be asserted as well.
 //!
 //! ### Ok
 //!
@@ -71,7 +71,7 @@
 //! assert_that(result).is_err();
 //! ```
 //!
-//! When the [Err]-value implements [PartialEq] one can use [and_error_equals](struct.ErrAsserter.html#method.and_error_equals)
+//! When the [`Err`]-value implements [`PartialEq`] one can use [`and_error_equals`](struct.ErrAsserter.html#method.and_error_equals)
 //!
 //! ```
 //! # use smoothy::assert_that;
@@ -82,7 +82,7 @@
 //! assert_that(result).is_err().and_error_equals(CustomError(String::from("Oh no!")));
 //! ```
 //!
-//! Alternativly one can assert the error message (given the error implements [Display](std::fmt::Display)):
+//! Alternatively one can assert the error message (given the error implements [Display](std::fmt::Display)):
 //!
 //! ```
 //! # use smoothy::assert_that;
@@ -106,7 +106,7 @@
 // enable more lint groups
 #![deny(clippy::pedantic, clippy::nursery)]
 // check documentation
-// #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
+#![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 // enable extra restriction lints
 #![deny(
     clippy::as_conversions,
@@ -159,16 +159,30 @@
     clippy::needless_pass_by_value
 )]
 
+pub use result::*;
+
 mod basic;
 mod implementation;
 mod result;
 
-pub use result::*;
-
+/// Main struct to enable various assertions on `AssertedType`
 pub struct AssertionBuilder<AssertedType> {
     pub(crate) value: AssertedType,
 }
 
+/// Entrypoint for all assertions
+///
+/// Enables various assertions on variable based on its type
+///
+/// # Examples
+/// ```
+/// # use smoothy::{assert_that, AssertionBuilder};
+/// #
+/// let assertable = String::from("Hello World!");
+/// let assertion: AssertionBuilder<String> = assert_that(assertable);
+/// // add your assertions here
+/// ```
+#[must_use]
 pub const fn assert_that<AssertedType>(value: AssertedType) -> AssertionBuilder<AssertedType> {
     AssertionBuilder { value }
 }

src/result/is_err.rs

@@ -1,11 +1,26 @@
 use crate::{implementation, AssertionBuilder};
-use std::fmt::{Debug, Display};
+use std::fmt::Debug;
 
 impl<OkValue, ErrValue> AssertionBuilder<Result<OkValue, ErrValue>>
 where
     OkValue: Debug,
     ErrValue: Debug,
 {
+    /// Asserts that the [Result] is an [Err].
+    ///
+    /// Allows the usage of chained assertions on an error-type (see [`ErrAsserter`]).
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// let result: Result<(), String> = Err(String::new());
+    ///
+    /// assert_that(result).is_err();
+    /// ```
+    ///
+    /// # Panics
+    /// When the [Result] is an [Ok]
     pub fn is_err(self) -> ErrAsserter<ErrValue> {
         implementation::assert(self.value.is_err(), "Result to be an error", &self.value);
 
@@ -15,26 +30,103 @@ where
     }
 }
 
+/// Enables various assertions on [Err]-values
 pub struct ErrAsserter<ErrValue> {
     value: ErrValue,
 }
 
-// In case the error does implement PartialEq
 impl<ErrValue> ErrAsserter<ErrValue>
 where
     ErrValue: Debug + PartialEq,
 {
+    /// Asserts that the asserted error is equal to the expected error.
+    ///
+    /// This is done by transforming the expected error to a instance of `ErrValue` by using the [Into]-trait
+    /// and then comparing both values with [`PartialEq`].
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// # use std::fmt::Display;
+    /// #
+    /// #[derive(Debug, PartialEq)]
+    /// pub struct ComparableError(String);
+    ///
+    /// let result: Result<(), ComparableError> = Err(ComparableError(String::from("Hello There")));
+    ///
+    /// assert_that(result)
+    ///     .is_err()
+    ///     .and_error_equals(ComparableError(String::from("Hello There")));
+    /// ```
+    ///
+    /// When the asserted error cannot be build but converted one can also use any type that implements [Into] the asserted error
+    ///
+    /// ```
+    /// # use smoothy::assert_that;
+    /// #
+    /// // The error type we want to assert
+    /// #[derive(Debug, PartialEq)]
+    /// pub struct NotConstructableError(String);
+    ///
+    /// // The error we can construct
+    /// pub struct ConvertableError(pub String);
+    ///
+    /// /* From-implementation */
+    /// # impl From<ConvertableError> for NotConstructableError {
+    /// #     fn from(error: ConvertableError) -> Self {
+    /// #         NotConstructableError(error.0)
+    /// #     }
+    /// # }
+    ///
+    /// let result: Result<(), NotConstructableError> = Err(NotConstructableError(String::from("Hello There")));
+    ///
+    /// assert_that(result)
+    ///     .is_err()
+    ///     .and_error_equals(ConvertableError(String::from("Hello There")));
+    /// ```
+    ///
+    /// # Panics
+    /// When the errors are not matching according to [`PartialEq`].
     pub fn and_error_equals(self, expected: impl Into<ErrValue>) {
         let expected: ErrValue = expected.into();
         implementation::assert_equals(self.value, expected);
     }
 }
 
-// In case the error does not implement PartialEq
 impl<ErrValue> ErrAsserter<ErrValue>
 where
-    ErrValue: Debug + Display,
+    ErrValue: Debug + ToString,
 {
+    /// Asserts that the asserted error message is equal to the expected string.
+    ///
+    /// This assertion can be used when the error does not implement [`PartialEq`] or the error cannot be constructed.
+    ///
+    /// The asserted error message is created by calling [`to_string`](ToString::to_string) on the error
+    ///
+    /// # Examples
+    /// ```
+    /// # use smoothy::assert_that;
+    /// # use std::fmt::Display;
+    /// #
+    /// #[derive(Debug)]
+    /// pub struct NonComparableError(String);
+    /// #
+    /// # impl Display for NonComparableError {
+    /// #     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    /// #         write!(f, "{}", self.0)
+    /// #     }
+    /// # }
+    ///
+    /// let result: Result<(), NonComparableError> =
+    /// Err(NonComparableError(String::from("Hello There")));
+    ///
+    /// assert_that(result)
+    ///     .is_err()
+    ///     .and_error_to_string_equals(String::from("Hello There"));
+    /// ```
+    ///
+    /// # Panics
+    /// When the error message is not equal to the expected error message.
     pub fn and_error_to_string_equals(self, expected: impl AsRef<str>) {
         implementation::assert_equals(self.value.to_string().as_ref(), expected.as_ref());
     }