Merge pull request #132 from semiotic-ai/129-document-rav-storage-ada…

…pater

Add document to RAV storage adapter, adapter mod, tap_manager mod

tap_core/src/adapters/mod.rs

@@ -1,6 +1,20 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+//! The adapters module provides interfaces that allow flexibility in storing and verifying TAP components.
+//!
+//! Each adapter should be defined by the user of the library based on their specific storage and verification requirements. This modular design
+//! allows for easy integration with various storage solutions and verification procedures, thereby making the library adaptable to a wide range
+//! of use cases.
+//!
+//! The following adapters are defined:
+//! - `collateral_adapter`: An interface for checking and updating collateral availability.
+//! - `rav_storage_adapter`: An interface for storing and retrieving/replacing RAVs.
+//! - `receipt_checks_adapter`: An interface for verifying TAP receipts.
+//! - `receipt_storage_adapter`: An interface for storing, retrieving, updating, and removing TAP receipts.
+//!
+//! In addition, this module also includes mock implementations of each adapter for testing and example purposes.
+
 pub mod collateral_adapter;
 pub mod rav_storage_adapter;
 pub mod receipt_checks_adapter;

tap_core/src/adapters/rav_storage_adapter.rs

@@ -3,10 +3,47 @@
 
 use crate::tap_manager::SignedRAV;
 
+/// `RAVStorageAdapter` defines a trait for storage adapters to handle `SignedRAV` data.
+///
+/// This trait is designed to be implemented by users of this library who want to
+/// customize the storage behavior of `SignedRAV` data. The error handling is also
+/// customizable by defining an `AdapterError` type, which must implement both `Error`
+/// and `Debug` from the standard library.
+///
+/// # Usage
+///
+/// The `update_last_rav` method should be used to update the last validated `SignedRAV`
+/// in the storage managed by the adapter. Errors during this operation should be
+/// captured and returned in the `AdapterError` format.
+///
+/// The `last_rav` method is designed to fetch the latest `SignedRAV` from the storage.
+/// If there is no `SignedRAV` available, it should return `None`. Any errors during
+/// this operation should be captured and returned as an `AdapterError`.
+///
+/// This trait is utilized by [crate::tap_manager], which relies on these
+/// operations for working with `SignedRAV` data.
+///
+/// # Example
+///
+/// For example code see [crate::adapters::rav_storage_adapter_mock]
+
 pub trait RAVStorageAdapter {
-    /// User defined error type;
+    /// Defines the user-specified error type.
+    ///
+    /// This error type should implement the `Error` and `Debug` traits from the standard library.
+    /// Errors of this type are returned to the user when an operation fails.
     type AdapterError: std::error::Error + std::fmt::Debug + Send + Sync + 'static;
 
+    /// Updates the storage with the latest validated `SignedRAV`.
+    ///
+    /// This method should be implemented to store the most recent validated `SignedRAV` into your chosen storage system.
+    /// Any errors that occur during this process should be captured and returned as an `AdapterError`.
     fn update_last_rav(&mut self, rav: SignedRAV) -> Result<(), Self::AdapterError>;
+
+    /// Retrieves the latest `SignedRAV` from the storage.
+    ///
+    /// This method should be implemented to fetch the latest `SignedRAV` from your storage system.
+    /// If no `SignedRAV` is available, this method should return `None`.
+    /// Any errors that occur during this process should be captured and returned as an `AdapterError`.
     fn last_rav(&self) -> Result<Option<SignedRAV>, Self::AdapterError>;
 }

tap_core/src/adapters/test/rav_storage_adapter_mock.rs

@@ -7,7 +7,35 @@ use thiserror::Error;
 
 use crate::{adapters::rav_storage_adapter::RAVStorageAdapter, tap_manager::SignedRAV};
 
+/// `RAVStorageAdapterMock` is a mock implementation of the `RAVStorageAdapter` trait.
+///
+/// It serves two main purposes:
+///
+/// 1. **Unit Testing**: The `RAVStorageAdapterMock` is primarily intended to be used for unit tests,
+///    providing a way to simulate the behavior of a real `RAVStorageAdapter` without requiring a real
+///    implementation. By using a mock implementation, you can create predictable behaviors and
+///    responses, enabling isolated and focused testing of the logic that depends on the `RAVStorageAdapter` trait.
+///
+/// 2. **Example Implementation**: New users of the `RAVStorageAdapter` trait can look to
+///    `RAVStorageAdapterMock` as a basic example of how to implement the trait.
+///
+/// Note: This mock implementation is not suitable for production use. Its methods simply manipulate a
+/// local `RwLock<Option<SignedRAV>>`, and it provides no real error handling.
+///
+/// # Usage
+///
+/// To use `RAVStorageAdapterMock`, first create an `Arc<RwLock<Option<SignedRAV>>>`, then pass it to
+/// `RAVStorageAdapterMock::new()`. Now, it can be used anywhere a `RAVStorageAdapter` is required.
+///
+/// ```rust
+/// use std::sync::{Arc, RwLock};
+/// use tap_core::{tap_manager::SignedRAV, adapters::rav_storage_adapter_mock::RAVStorageAdapterMock};
+///
+/// let rav_storage: Arc<RwLock<Option<SignedRAV>>> = Arc::new(RwLock::new(None));
+/// let adapter = RAVStorageAdapterMock::new(rav_storage);
+/// ```
 pub struct RAVStorageAdapterMock {
+    /// local RAV store with rwlocks to allow sharing with other compenents as needed
     rav_storage: Arc<RwLock<Option<SignedRAV>>>,
 }
 

tap_core/src/tap_manager/mod.rs

@@ -1,14 +1,14 @@
 // Copyright 2023-, Semiotic AI, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-//! The tap_manager is used to manage receipt and RAV validation and storage flow
+//! The `tap_manager` module provides facilities for managing TAP receipt and RAV validation, as well as storage flow.
 //!
-//! The tap_manager
+//! This module should be the primary interface for the receiver of funds to verify, store, and manage TAP receipts and RAVs.
+//! The `Manager` struct within this module allows the user to specify what checks should be performed on receipts, as well as
+//! when these checks should occur (either when a receipt is first received, or when it is being added to a RAV request).
 //!
-//! Receipts are used as single transaction promise of payment. A payment sender
-//! creates a receipt and ECDSA signs it, then sends it to a payment receiver.
-//! The payment receiver would verify the received receipt and store it to be
-//! accumulated with other received receipts in the future.
+//! The `Manager` uses user-defined adapters (see [crate::adapters]) for check and storage handling.
+//! This design offers a high degree of flexibility, letting the user define their own behavior for these critical operations.
 
 mod manager;
 mod rav_request;