docs: improve doc comments

src/account.rs

@@ -8,6 +8,40 @@ use rust_decimal_macros::dec;
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
 
+/// An abstraction over the balances of a client.
+///
+/// The only way of interacting with the account is through [`AccountActivity`] events supplied via
+/// [`Account::transaction`].
+///
+/// # Balances
+///
+/// An account manages the following balances:
+///
+/// | Type      | Description                                                                |
+/// |-----------|----------------------------------------------------------------------------|
+/// | available | Accessible for transactions like withdrawals, purchases, or transfers.     |
+/// | held      | Temporarily unavailable due to pending transactions, deposits, or disputes |
+/// | total     | Full balance in the account, including both the available and held funds   |
+///
+/// # Security
+///
+/// ## Transactions
+///
+/// For auditing purposes, all [transactions] are logged, even in cases where the transaction
+/// ultimately fails. This ensures that failed transactions are not retried with altered payloads.
+/// If a transaction fails once, it will be recorded alongside its ID and thus not executed again.
+///
+/// ## Disputes
+///
+/// A [dispute case](crate::dispute::DisputeCase) must follow all required steps in the process.
+/// [Resolutions] and [chargebacks] are only processed if the corresponding transaction has been
+/// properly disputed beforehand.
+///
+/// Disputes for non-existent transactions are silently ignored.
+///
+/// [transactions]: crate::transaction::Transaction
+/// [Resolutions]: crate::account_activity::AccountActivity::Resolve
+/// [chargebacks]: crate::account_activity::AccountActivity::Chargeback
 #[derive(Debug, PartialEq, serde::Serialize)]
 pub struct Account {
     #[serde(rename = "client")]
@@ -45,22 +79,18 @@ impl Account {
         self.client_id
     }
 
-    /// Returns the total funds that are available.
     pub fn available(&self) -> Decimal {
         self.available
     }
 
-    /// Returns the total funds that disputed.
     pub fn held(&self) -> Decimal {
         self.held
     }
 
-    /// Returns the total funds that are [`available`](Self::available) or [`held`](Self::held).
     pub fn total(&self) -> Decimal {
         self.total
     }
 
-    /// Returns whether the account is locked.
     pub fn is_locked(&self) -> bool {
         self.locked
     }
@@ -165,15 +195,6 @@ impl Account {
     }
 
     /// Process an account activity, which could either be a transaction or a dispute activity.
-    ///
-    /// # Security
-    /// For auditing purposes, all [transactions](crate::transaction::Transaction) are logged, even
-    /// in cases where the transaction ultimately fails. This ensures that failed transactions are
-    /// not retried with altered payloads. If a transaction fails once, it will be recorded
-    /// alongside its ID and thus not executed again.
-    ///
-    /// [Dispute cases](crate::dispute::DisputeCase) are logged temporarily and retained only until
-    /// they are fully resolved.
     pub fn transaction(&mut self, activity: AccountActivity) -> AccountActivityResult<()> {
         if self.is_locked() {
             return Err(FailedTransaction("account locked".into()));

src/account_activity.rs

@@ -27,6 +27,8 @@ pub enum AccountActivityError {
 
 pub type AccountActivityResult<T> = Result<T, AccountActivityError>;
 
+/// Account activities are events that influence an [`Account`]s balance. These events could either 
+/// be [`Transaction`]s or [`DisputeCase`]s.
 #[derive(Debug, PartialEq, Clone, Copy)]
 pub enum AccountActivity {
     /// A [`Transaction`] where funds are added to an account, increasing the available and total

src/processor.rs

@@ -4,8 +4,8 @@ use std::collections::HashMap;
 use std::error::Error;
 use tracing::warn;
 
-// TODO: This fn is public to be able to benchmark it. This should probably be handled with a bench 
-//       feature instead.
+// TODO: This fn is public to be able to benchmark it. This should better be handled with a
+//       bench-feature instead.
 pub fn process_activities<I, E>(activities: I) -> Vec<Account>
 where
     E: Error,
@@ -36,13 +36,19 @@ where
     accounts.into_values().collect()
 }
 
+/// The processor handles reading account activity records from a source, processing these activities,
+/// and generating account balances as the output.
 pub trait Processor {
     type Error: Error;
 
+    /// Returns an iterator over the parsed records of the input data.
     fn iter_input(&mut self) -> impl Iterator<Item=Result<AccountActivity, Self::Error>>;
 
+    /// Takes a vector of accounts and serializes it into the output format.
     fn write(&mut self, accounts: Vec<Account>) -> Result<(), Self::Error>;
 
+    /// Processes the [`AccountActivity`] data supplied by [`Processor::iter_input`] and generates
+    /// account balance data that is serialized by [`Processor::write`].
     fn process(&mut self) -> Result<(), Self::Error> {
         let activity_records = self.iter_input();
         let accounts = process_activities(activity_records);

src/processors/csv/deserialize.rs

@@ -1,3 +1,9 @@
+//! A custom [`Deserialize`](serde::de::Deserialize) implementation that allows CSV records of
+//! varying lengths to be deserialized into an enum of structs, addressing the limitation that the
+//! [`csv`](csv) crate does currently not support this.
+//!
+//! For more details, see [this issue](https://github.com/BurntSushi/rust-csv/issues/211).
+//!
 use crate::account_activity::AccountActivity;
 use crate::dispute::DisputeCase;
 use crate::transaction::Transaction;

src/transaction.rs

@@ -13,8 +13,8 @@ impl Display for TransactionID {
 }
 
 /// A transaction is a financial activity or event where a value is exchanged between two parties.
-/// In the context of banking or finance, it refers to any movement of funds involving accounts,
-/// typically involving deposits, withdrawals, transfers, or payments.
+/// In the context of finance, it refers to any movement of funds involving accounts, typically 
+/// involving deposits, withdrawals, transfers, or payments.
 #[derive(serde::Deserialize, Debug, PartialEq, Clone, Copy)]
 pub struct Transaction {
     #[serde(rename = "tx")]