chore: adding doc on other struct

Signed-off-by: Simon Paitrault <[email protected]>

crates/topos-tce-storage/src/fullnode/mod.rs

@@ -26,6 +26,18 @@ use self::locking::LockGuards;
 
 mod locking;
 
+/// Store to manage FullNode data
+///
+/// The [`FullNodeStore`] is responsible for storing and exposing the data that is
+/// needed by a full node to perform its duties.
+///
+/// The responsabilities of the [`FullNodeStore`] are:
+///
+/// - Storing and exposing the certificates that are delivered
+/// - Storing and exposing the current state of the streams and the different positions
+///
+/// To do so, it implements [`ReadStore`] / [`WriteStore`] and use multiple tables and store such
+/// as [`ValidatorPerpetualTables`], [`EpochValidatorsStore`] and [`IndexTables`]
 pub struct FullNodeStore {
     certificate_lock_guards: LockGuards<CertificateId>,
     subnet_lock_guards: LockGuards<SubnetId>,

crates/topos-tce-storage/src/lib.rs

@@ -30,21 +30,6 @@
 //! The underlying mechanisms of how data is stored is fairly simple, it relies a lot on [`rocksdb`] and will
 //! be describe below.
 //!
-//! As an example, in order to create a new [`EpochValidatorsStore`](struct@epoch::EpochValidatorsStore) you need to provide a
-//! path where the [`rocksdb`] database will be placed:
-//!
-//! ```
-//! # use topos_tce_storage::epoch;
-//! use epoch::EpochValidatorsStore;
-//! # use std::str::FromStr;
-//! # use std::path::PathBuf;
-//! # use std::sync::Arc;
-//! # let mut path = PathBuf::from_str(env!("CARGO_MANIFEST_DIR")).unwrap();
-//! # path.push("./../../target/tmp/");
-//! path.push("epoch");
-//! let store: Arc<EpochValidatorsStore> = EpochValidatorsStore::new(path).unwrap();
-//! ```
-//!
 //! ## Special Considerations
 //!
 //! When using the storage layer, you need to be aware of the following:

crates/topos-tce-storage/src/store.rs

@@ -10,30 +10,56 @@ use crate::{
     errors::StorageError, CertificatePositions, CertificateTargetStreamPosition, SourceHead,
 };
 
+/// This trait exposes common methods between
+/// [`ValidatorStore`](struct@super::validator::ValidatorStore) and
+/// [`FullNodeStore`](struct@super::fullnode::FullNodeStore) to write data.
+///
+/// All methods are `async` to allow the implementation to deal with write concurrency.
 #[async_trait]
 pub trait WriteStore: Send {
-    /// Insert a CertificateDelivered in the differents tables. Removing pending if needed.
+    /// Insert a [`CertificateDelivered`] in the storage. Returns its positions
+    /// in the source and target streams.
+    ///
+    /// Info: The [`ValidatorStore`](struct@super::validator::ValidatorStore) implementation
+    /// is checking for a [`PendingCertificateId`](type@super::PendingCertificateId) and remove if
+    /// the certificate is successfully inserted.
     async fn insert_certificate_delivered(
         &self,
         certificate: &CertificateDelivered,
     ) -> Result<CertificatePositions, StorageError>;
 
-    /// Insert multiple CertificateDelivered
+    /// Insert multiple [`CertificateDelivered`] in the storage.
+    ///
+    /// See [`insert_certificate_delivered`](fn@WriteStore::insert_certificate_delivered) for more
+    /// details
     async fn insert_certificates_delivered(
         &self,
         certificates: &[CertificateDelivered],
     ) -> Result<(), StorageError>;
 }
 
+/// This trait exposes common methods between
+/// [`ValidatorStore`](struct@super::validator::ValidatorStore) and
+/// [`FullNodeStore`](struct@super::fullnode::FullNodeStore) to read data.
 pub trait ReadStore: Send {
+    /// Try to get a SourceHead of a subnet
+    ///
+    /// Returns `Ok(None)` if the subnet is not found, meaning that no certificate are currently
+    /// delivered for this particular subnet.
     fn get_source_head(&self, subnet_id: &SubnetId) -> Result<Option<SourceHead>, StorageError>;
-    /// Try to get a Certificate
+
+    /// Try to get a [`CertificateDelivered`]
+    ///
+    /// Returns `Ok(None)` if the certificate is not found, meaning that the certificate is either
+    /// inexisting or not yet delivered.
     fn get_certificate(
         &self,
         certificate_id: &CertificateId,
     ) -> Result<Option<CertificateDelivered>, StorageError>;
 
-    /// Try to get multiple certificates at once
+    /// Try to get multiple [`CertificateDelivered`] at once.
+    ///
+    /// See [`get_certificate`](fn@ReadStore::get_certificate)
     fn get_certificates(
         &self,
         certificate_ids: &[CertificateId],
@@ -46,6 +72,9 @@ pub trait ReadStore: Send {
     ) -> Result<Option<CertificateSourceStreamPosition>, StorageError>;
 
     /// Returns the local checkpoint
+    ///
+    /// A `Checkpoint` is the representation of the state of delivery, it is a list of [`SubnetId`]
+    /// with the associated [`SourceHead`]
     fn get_checkpoint(&self) -> Result<HashMap<SubnetId, SourceHead>, StorageError>;
 
     /// Returns the certificates delivered by a source subnet from a position.
@@ -55,12 +84,14 @@ pub trait ReadStore: Send {
         limit: usize,
     ) -> Result<Vec<(CertificateDelivered, CertificateSourceStreamPosition)>, StorageError>;
 
+    /// Returns the certificates delivered to a target subnet from a position.
     fn get_target_stream_certificates_from_position(
         &self,
         position: CertificateTargetStreamPosition,
         limit: usize,
     ) -> Result<Vec<(CertificateDelivered, CertificateTargetStreamPosition)>, StorageError>;
 
+    /// Returns the list of source subnet that delivered certificates to a target subnet
     fn get_target_source_subnet_list(
         &self,
         target_subnet_id: &SubnetId,

crates/topos-tce-storage/src/validator/mod.rs

@@ -23,12 +23,19 @@ use crate::{
     CertificatePositions, CertificateTargetStreamPosition, PendingCertificateId, SourceHead,
 };
 
-pub(crate) use self::tables::ValidatorPendingTables;
+pub use self::tables::ValidatorPendingTables;
 pub use self::tables::ValidatorPerpetualTables;
 
 mod tables;
 
-/// Contains all persistent data about the validator
+/// Store to manage Validator data
+///
+/// The [`ValidatorStore`] is composed of a [`FullNodeStore`] and a [`ValidatorPendingTables`].
+///
+/// As the [`FullNodeStore`] is responsible of keeping and managing every data that are persistent,
+/// the [`ValidatorStore`] is forwarding everything to it. The crucial point is that the
+/// [`ValidatorStore`] is managing the different pending pool using the [`ValidatorPendingTables`].
+///
 pub struct ValidatorStore {
     pub(crate) pending_tables: ValidatorPendingTables,
     pub(crate) fullnode_store: Arc<FullNodeStore>,
@@ -48,28 +55,37 @@ impl ValidatorStore {
         Ok(store)
     }
 
+    /// Returns the [`FullNodeStore`] used by the [`ValidatorStore`]
     pub fn get_fullnode_store(&self) -> Arc<FullNodeStore> {
         self.fullnode_store.clone()
     }
 
+    /// Returns the number of certificates in the pending pool
     pub fn count_pending_certificates(&self) -> Result<usize, StorageError> {
         Ok(self.pending_tables.pending_pool.iter()?.count())
     }
 
+    /// Try to return the [`PendingCertificateId`] for a [`CertificateId`]
+    ///
+    /// Return `Ok(None)` if the `certificate_id` is not found.
     pub fn get_pending_id(
         &self,
         certificate_id: &CertificateId,
     ) -> Result<Option<PendingCertificateId>, StorageError> {
         Ok(self.pending_tables.pending_pool_index.get(certificate_id)?)
     }
 
+    /// Try to return the [`Certificate`] for a [`PendingCertificateId`]
+    ///
+    /// Return `Ok(None)` if the `pending_id` is not found.
     pub fn get_pending_certificate(
         &self,
         pending_id: &PendingCertificateId,
     ) -> Result<Option<Certificate>, StorageError> {
         Ok(self.pending_tables.pending_pool.get(pending_id)?)
     }
 
+    /// Returns the entier pending_pool
     pub fn get_pending_certificates(
         &self,
     ) -> Result<Vec<(PendingCertificateId, Certificate)>, StorageError> {