Add documentation

.clippy.toml

@@ -0,0 +1,2 @@
+disallowed-names = [ "TYPES" ]
+doc-valid-idents = [ "HotShot", ".." ]

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"
 

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,

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,