docs(eventually): add some missing documentation (#250)

* docs(aggregate/repository): add documentation

* docs(event/store): add documentation

* test(postgres): assert eventstore test failure using strings

Author: ar3s3ru

eventually-postgres/tests/event_store.rs

@@ -168,25 +168,29 @@ async fn it_handles_concurrent_writes_to_the_same_stream() {
     .into()];
 
     let result = futures::join!(
-        event_store
-            .append(
-                event_stream_id.clone(),
-                StreamVersionExpected::MustBe(0),
-                expected_events.clone(),
-            )
-            .map_err(Option::<version::ConflictError>::from),
-        event_store
-            .append(
-                event_stream_id.clone(),
-                StreamVersionExpected::MustBe(0),
-                expected_events,
-            )
-            .map_err(Option::<version::ConflictError>::from)
+        event_store.append(
+            event_stream_id.clone(),
+            StreamVersionExpected::MustBe(0),
+            expected_events.clone(),
+        ),
+        event_store.append(
+            event_stream_id.clone(),
+            StreamVersionExpected::MustBe(0),
+            expected_events,
+        )
     );
 
     match result {
         (Ok(_), Err(err)) | (Err(err), Ok(_)) => {
-            assert!(Option::<version::ConflictError>::from(err).is_some())
+            let expected_err = event::AppendError::Concurrency(version::ConflictError {
+                expected: 0,
+                actual: 1,
+            });
+
+            let actual_err_msg = format!("{}", err);
+            let expected_err_msg = format!("{}", expected_err);
+
+            assert_eq!(expected_err_msg, actual_err_msg);
         }
         (first, second) => panic!(
             "invalid state detected, first: {:?}, second: {:?}",

eventually/src/aggregate/repository.rs

@@ -1,3 +1,9 @@
+//! Module containing the definition of a [Repository], to fetch and store
+//! Aggregate Roots from a data store.
+//!
+//! If you are looking for the Event-sourced implementation of an Aggregate Repository,
+//! take a look at [EventSourced].
+
 use std::{fmt::Debug, marker::PhantomData};
 
 use async_trait::async_trait;
@@ -13,27 +19,37 @@ pub enum GetError<I> {
     /// desired Aggregate [Root] could not be found in the data store.
     #[error("aggregate root was not found")]
     NotFound,
+
+    /// Error variant returned by [`Repository::get`] when the underlying
+    /// concrete implementation has encountered an error.
     #[error(transparent)]
     Inner(#[from] I),
 }
 
+/// Getter is a [Repository] trait used to get an [aggregate::Root]
+/// instance from a data store.
 #[async_trait]
 pub trait Getter<T>: Send + Sync
 where
     T: Aggregate,
 {
+    /// Error type returned by the concrete implementation of the trait.
+    /// It is returned in [get] using [GetError::Other].
     type Error: Send + Sync;
 
     /// Loads an Aggregate Root instance from the data store,
     /// referenced by its unique identifier.
     async fn get(&self, id: &T::Id) -> Result<aggregate::Root<T>, GetError<Self::Error>>;
 }
 
+/// Saver is a [Repository] trait used to save an [aggregate::Root]
+/// instance to a data store.
 #[async_trait]
 pub trait Saver<T>: Send + Sync
 where
     T: Aggregate,
 {
+    /// Error type returned by the concrete implementation of the trait.
     type Error: Send + Sync;
 
     /// Saves a new version of an Aggregate Root instance to the data store.

eventually/src/event/store.rs

@@ -1,3 +1,6 @@
+//! Contains implementations of the [event::Store] trait and connected abstractions,
+//! such as the [std::collections::HashMap]'s based [InMemory] Event Store implementation.
+
 use std::{
     collections::HashMap,
     convert::Infallible,
@@ -32,6 +35,8 @@ where
     }
 }
 
+/// In-memory implementation of [event::Store] trait,
+/// backed by a thread-safe [std::collections::HashMap].
 #[derive(Debug, Clone)]
 pub struct InMemory<Id, Evt>
 where
@@ -139,6 +144,11 @@ where
     }
 }
 
+/// Decorator type for an [event::Store] implementation that tracks the list of
+/// recorded Domain Events through it.
+///
+/// Useful for testing purposes, i.e. asserting that Domain Events written throguh
+/// this Event Store instance are the ones expected.
 #[derive(Debug, Clone)]
 pub struct Tracking<T, StreamId, Event>
 where
@@ -158,13 +168,15 @@ where
     StreamId: Clone + Send + Sync,
     Event: message::Message + Clone + Send + Sync,
 {
+    /// Returns the list of recoded Domain Events through this decorator so far.
     pub fn recorded_events(&self) -> Vec<event::Persisted<StreamId, Event>> {
         self.events
             .read()
             .expect("acquire lock on recorded events list")
             .clone()
     }
 
+    /// Resets the list of recorded Domain Events through this decorator.
     pub fn reset_recorded_events(&self) {
         self.events
             .write()
@@ -232,12 +244,16 @@ where
     }
 }
 
+/// Extension trait that can be used to pull in supertypes implemented
+/// in this module.
 pub trait EventStoreExt<StreamId, Event>:
     event::Store<StreamId, Event> + Send + Sync + Sized
 where
     StreamId: Clone + Send + Sync,
     Event: message::Message + Clone + Send + Sync,
 {
+    /// Returns a [Tracking] instance that decorates the original [event::Store]
+    /// instanca this method has been called on.
     fn with_recorded_events_tracking(self) -> Tracking<Self, StreamId, Event> {
         Tracking {
             store: self,