From 2b1c75c95f8850ea41a7c75a4b7e13ef9d6db86a Mon Sep 17 00:00:00 2001
From: Artemii Gerasimovich <artemii@espressosys.com>
Date: Tue, 22 Oct 2024 14:37:56 +0200
Subject: [PATCH] Add documentation

---
 .clippy.toml                                  |  2 ++
 Cargo.toml                                    |  1 +
 crates/marketplace/src/testing/integration.rs | 13 +++++++++++++
 crates/shared/src/testing/mod.rs              |  2 ++
 4 files changed, 18 insertions(+)
 create mode 100644 .clippy.toml

diff --git a/.clippy.toml b/.clippy.toml
new file mode 100644
index 0000000..70b4d54
--- /dev/null
+++ b/.clippy.toml
@@ -0,0 +1,2 @@
+disallowed-names = [ "TYPES" ]
+doc-valid-idents = [ "HotShot", ".." ]
diff --git a/Cargo.toml b/Cargo.toml
index d66cab5..a4cfd2c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -54,6 +54,7 @@ unexpected_cfgs = { level = "warn", check-cfg = [
 ] }
 
 [workspace.lints.clippy]
+disallowed-names = "deny"
 doc_markdown = "deny"
 doc_link_with_quotes = "deny"
 
diff --git a/crates/marketplace/src/testing/integration.rs b/crates/marketplace/src/testing/integration.rs
index 62b6b68..d2099cf 100644
--- a/crates/marketplace/src/testing/integration.rs
+++ b/crates/marketplace/src/testing/integration.rs
@@ -1,3 +1,6 @@
+//! This module implements interfaces necessary to run marketplace builder
+//! in HotShot testing harness.
+
 use std::{collections::HashMap, fmt::Display, marker::PhantomData, sync::Arc, time::Duration};
 
 use async_compatibility_layer::art::async_spawn;
@@ -33,6 +36,9 @@ use crate::{
 
 const BUILDER_CHANNEL_CAPACITY: usize = 1024;
 
+/// Testing configuration for marketplace builder
+/// Stores hooks that will be used in the builder in a type-erased manner,
+/// allowing for runtime configuration of hooks to use in tests.
 struct TestMarketplaceBuilderConfig<Types>
 where
     Types: NodeType,
@@ -51,6 +57,9 @@ where
     }
 }
 
+/// [`TestBuilderImplementation`] for marketplace builder.
+/// Passed as a generic parameter to [`TestRunner::run_test`], it is be used
+/// to instantiate builder API and builder task.
 struct MarketplaceBuilderImpl {}
 
 #[async_trait]
@@ -65,6 +74,9 @@ where
 {
     type Config = TestMarketplaceBuilderConfig<Types>;
 
+    /// This is mostly boilerplate to instantiate and start [`ProxyGlobalState`] APIs and initial [`BuilderState`]'s event loop.
+    /// [`BuilderTask`] it returns will be injected into consensus runtime by HotShot testing harness and
+    /// will forward transactions from hotshot event stream to the builder.
     async fn start(
         n_nodes: usize,
         url: Url,
@@ -156,6 +168,7 @@ where
     }
 }
 
+/// Marketplace builder task. Stores all the necessary information to run builder service
 struct MarketplaceBuilderTask<Types>
 where
     Types: NodeType,
diff --git a/crates/shared/src/testing/mod.rs b/crates/shared/src/testing/mod.rs
index ee0878b..6f5654d 100644
--- a/crates/shared/src/testing/mod.rs
+++ b/crates/shared/src/testing/mod.rs
@@ -50,6 +50,8 @@ impl TryFrom<&TransactionPayload> for TestTransaction {
     }
 }
 
+/// Run a builder test. Thin wrapper around `TestRunner::run_test`, injecting transaction generation
+/// and validation tasks based on `validation_config` and `transaction_generation_config` respectively.
 pub async fn run_test<V: Versions, BuilderImpl: TestBuilderImplementation<TestTypes>>(
     description: TestDescription<TestTypes, MemoryImpl, V>,
     validation_config: BuilderValidationConfig,