adapter - docs improvements

Author: elpiel

adapter/src/adapter.rs

@@ -25,7 +25,18 @@ pub(crate) mod state {
 }
 
 #[derive(Debug)]
-/// [`Adapter`] struct
+/// The [`Adapter`] struct and it's states.
+///
+/// Used for communication with the underlying client implementation.
+///
+/// # Available adapters
+///
+/// 2 Adapters are available in this crate:
+/// - Ethereum
+///   - [`crate::ethereum::LockedAdapter`] and [`crate::ethereum::UnlockedAdapter`]
+///   - Client implementation [`crate::Ethereum`] for chains compatible with EVM.
+/// - Dummy
+///   - [`crate::dummy::Adapter`] and it's client implementation [`crate::Dummy`] for testing.
 pub struct Adapter<C, S = state::LockedState> {
     /// client in a specific state - Locked or Unlocked
     pub client: Arc<C>,
@@ -119,7 +130,7 @@ where
     }
 
     /// Creates a `Session` from a provided Token by calling the Contract.
-    /// Does **not** cache the (`Token`, `Session`) pair.
+    /// Does **not** cache the (`Token`, [`Session`]) pair.
     async fn session_from_token(&self, token: &str) -> Result<Session, Error> {
         self.client
             .session_from_token(token)

adapter/src/client.rs

@@ -1,3 +1,9 @@
+//! The Client traits that define the actions for each state.
+//!
+//! - [`Locked`]
+//! - [`Unlocked`]
+//! - [`Unlockable`]
+
 use crate::primitives::{Deposit, Session};
 use async_trait::async_trait;
 use primitives::{Address, Channel, ValidatorId};

adapter/src/dummy.rs

@@ -1,3 +1,5 @@
+//! The [`Dummy`] client for the [`Adapter`].
+//! 
 use crate::{
     prelude::*,
     primitives::{Deposit, Session},
@@ -11,8 +13,8 @@ use std::{collections::HashMap, sync::Arc};
 
 pub type Adapter<S> = crate::Adapter<Dummy, S>;
 
+/// Dummy adapter implementation intended for testing.
 #[derive(Debug, Clone)]
-/// Dummy adapter implementation.
 pub struct Dummy {
     /// Who am I
     identity: ValidatorId,

adapter/src/error.rs

@@ -4,6 +4,8 @@ use thiserror::Error;
 
 pub(crate) type BoxError = Box<dyn StdError + Send + Sync>;
 
+/// The error used by the [`crate::Adapter`] to wrap any custom error from the client
+/// and the kinds of errors that the [`crate::Adapter`] can return.
 #[derive(Debug, Error)]
 #[error("{inner}")]
 pub struct Error {

adapter/src/ethereum.rs

@@ -1,20 +1,22 @@
+//! The [`Ethereum`] client for the [`Adapter`].
+
 use ethstore::{ethkey::Password, SafeAccount};
 
 use once_cell::sync::Lazy;
 use serde_json::Value;
 use web3::signing::keccak256;
 
-use crate::{LockedState, UnlockedState};
+use crate::{LockedState, UnlockedState, Adapter};
 
 pub use {
     client::{get_counterfactual_address, Ethereum, Options},
     error::Error,
 };
 
-pub type UnlockedAdapter = crate::Adapter<client::Ethereum<UnlockedWallet>, UnlockedState>;
-pub type LockedAdapter = crate::Adapter<client::Ethereum<LockedWallet>, LockedState>;
-pub type LockedClient = client::Ethereum<LockedWallet>;
-pub type UnlockedClient = client::Ethereum<UnlockedWallet>;
+pub type UnlockedAdapter = Adapter<client::Ethereum<UnlockedWallet>, UnlockedState>;
+pub type LockedAdapter = Adapter<client::Ethereum<LockedWallet>, LockedState>;
+pub type LockedClient = Ethereum<LockedWallet>;
+pub type UnlockedClient = Ethereum<UnlockedWallet>;
 
 mod channel;
 mod client;

adapter/src/lib.rs

@@ -4,20 +4,21 @@ pub use {
         Adapter,
     },
     error::Error,
+    dummy::Dummy,
+    ethereum::Ethereum,
 };
 
-pub use dummy::Dummy;
-pub use ethereum::Ethereum;
-
-/// only re-export types from the `primitives` crate that are being used by the [`crate::Adapter`].
+/// Primitives used by the [`Adapter`].
+/// Including re-exported types from the `primitives` crate that are being used.
 pub mod primitives {
     use serde::{Deserialize, Serialize};
 
-    /// Re-export all the types used from the [`primitives`] crate.
     pub use ::primitives::{Address, BigNum, Channel, ValidatorId};
 
     use crate::ethereum::WalletState;
 
+    /// The [`Deposit`] struct with [`BigNum`] values.
+    /// Returned by [`crate::client::Locked::get_deposit`]
     pub type Deposit = ::primitives::Deposit<primitives::BigNum>;
 
     /// A helper type that allows you to use either of them
@@ -38,29 +39,30 @@ pub mod primitives {
         }
     }
 
+    /// [`Session`] struct returned by the [`crate::Adapter`] when [`crate::client::Locked::session_from_token`] is called.
     #[derive(Debug, Clone, Serialize, Deserialize)]
     pub struct Session {
         pub era: i64,
         pub uid: Address,
     }
 }
 
-/// Re-export of the [`crate::client`] traits.
+/// Re-export of the [`crate::client`] traits and the states of the [`Adapter`].
 pub mod prelude {
     /// Re-export traits used for working with the [`crate::Adapter`].
     pub use crate::client::{Locked, Unlockable, Unlocked};
 
     pub use crate::{LockedState, UnlockedState};
 }
 
-/// The [`Adapter`] struct and it's states
-/// Used for communication with underlying implementation.
-/// 2 Adapters are available in this crate:
-/// - [`crate::ethereum::LockedAdapter`] and [`crate::ethereum::UnlockedAdapter`] and it's client implementation [`crate::Ethereum`] for chains compatible with EVM.
-/// - [`crate::dummy::Adapter`] and it's client implementation [`crate::Dummy`] for testing.
 mod adapter;
+
+
 pub mod client;
+
 pub mod dummy;
+
 mod error;
+
 pub mod ethereum;
 pub mod util;

adapter/src/util.rs

@@ -1,7 +1,8 @@
+//! Utilities for working with the `State root` and the `Balances`
+
 use thiserror::Error;
 
-/// Re-export all the types used from the [`primitives`] crate.
-pub use ::primitives::{Address, BigNum, Channel, ValidatorId};
+use crate::primitives::{Address, BigNum};
 use web3::{
     ethabi::{encode, Address as EthAddress, Token},
     signing::keccak256,

test_harness/src/lib.rs

@@ -70,7 +70,7 @@ pub struct TestValidator {
     pub sentry_config: sentry::application::Config,
     /// Sentry REST API url
     pub sentry_url: ApiUrl,
-    /// Used for the _Sentry REST API_ [`sentry::Application`] as well as the _Validator worker_ [`validator_worker::worker::Args`]
+    /// Used for the _Sentry REST API_ [`sentry::Application`] as well as the _Validator worker_ [`validator_worker::Worker`]
     pub config: Config,
     /// Prefix for sentry logger
     pub sentry_logger_prefix: String,