From 5779fa4ad01e111ef96a9911aba986b6d1425a4d Mon Sep 17 00:00:00 2001
From: Thomas Coratger <60488569+tcoratger@users.noreply.github.com>
Date: Thu, 21 Sep 2023 15:22:26 +0200
Subject: [PATCH] feat(interfaces): better doc for `BlockValidationError` and
 `BlockExecutionError` (#4708)

---
 crates/interfaces/src/executor.rs | 78 +++++++++++++++++++++++++------
 1 file changed, 63 insertions(+), 15 deletions(-)

diff --git a/crates/interfaces/src/executor.rs b/crates/interfaces/src/executor.rs
index 35570bb86d..0990e99023 100644
--- a/crates/interfaces/src/executor.rs
+++ b/crates/interfaces/src/executor.rs
@@ -5,29 +5,67 @@ use thiserror::Error;
 #[allow(missing_docs)]
 #[derive(Error, Debug, Clone, PartialEq, Eq)]
 pub enum BlockValidationError {
+    /// EVM error with transaction hash and message
     #[error("EVM reported invalid transaction ({hash:?}): {message}")]
-    EVM { hash: H256, message: String },
+    EVM {
+        /// The hash of the transaction
+        hash: H256,
+        /// Error message
+        message: String,
+    },
+    /// Error when recovering the sender for a transaction
     #[error("Failed to recover sender for transaction")]
     SenderRecoveryError,
+    /// Error when incrementing balance in post execution
     #[error("Incrementing balance in post execution failed")]
     IncrementBalanceFailed,
+    /// Error when receipt root doesn't match expected value
     #[error("Receipt root {got:?} is different than expected {expected:?}.")]
-    ReceiptRootDiff { got: H256, expected: H256 },
+    ReceiptRootDiff {
+        /// The actual receipt root
+        got: H256,
+        /// The expected receipt root
+        expected: H256,
+    },
+    /// Error when header bloom filter doesn't match expected value
     #[error("Header bloom filter {got:?} is different than expected {expected:?}.")]
-    BloomLogDiff { got: Box<Bloom>, expected: Box<Bloom> },
+    BloomLogDiff {
+        /// The actual bloom filter
+        got: Box<Bloom>,
+        /// The expected bloom filter
+        expected: Box<Bloom>,
+    },
+    /// Error when transaction gas limit exceeds available block gas
     #[error("Transaction gas limit {transaction_gas_limit} is more than blocks available gas {block_available_gas}")]
     TransactionGasLimitMoreThanAvailableBlockGas {
+        /// The transaction's gas limit
         transaction_gas_limit: u64,
+        /// The available block gas
         block_available_gas: u64,
     },
+    /// Error when block gas used doesn't match expected value
     #[error("Block gas used {got} is different from expected gas used {expected}.\nGas spent by each transaction: {gas_spent_by_tx:?}\n")]
-    BlockGasUsed { got: u64, expected: u64, gas_spent_by_tx: Vec<(u64, u64)> },
+    BlockGasUsed {
+        /// The actual gas used
+        got: u64,
+        /// The expected gas used
+        expected: u64,
+        /// Gas spent by each transaction
+        gas_spent_by_tx: Vec<(u64, u64)>,
+    },
+    /// Error for pre-merge block
     #[error("Block {hash:?} is pre merge")]
-    BlockPreMerge { hash: H256 },
+    BlockPreMerge {
+        /// The hash of the block
+        hash: H256,
+    },
+    /// Error when total difficulty is missing
     #[error("Missing total difficulty")]
     MissingTotalDifficulty { hash: H256 },
+    /// Error for EIP-4788 when parent beacon block root is missing
     #[error("EIP-4788 Parent beacon block root missing for active Cancun block")]
     MissingParentBeaconBlockRoot,
+    /// Error for Cancun genesis block when parent beacon block root is not zero
     #[error("The parent beacon block root is not zero for Cancun genesis block")]
     CancunGenesisParentBeaconBlockRootNotZero,
 }
@@ -36,27 +74,37 @@ pub enum BlockValidationError {
 #[allow(missing_docs)]
 #[derive(Error, Debug, Clone, PartialEq, Eq)]
 pub enum BlockExecutionError {
+    /// Validation error, transparently wrapping `BlockValidationError`
     #[error(transparent)]
     Validation(#[from] BlockValidationError),
+    /// Pruning error, transparently wrapping `PrunePartError`
     #[error(transparent)]
     Pruning(#[from] PrunePartError),
-
-    // === misc provider error ===
+    /// Error representing a provider error
     #[error("Provider error")]
     ProviderError,
-
-    // === transaction errors ===
+    /// Transaction error on revert with inner details
     #[error("Transaction error on revert: {inner:?}")]
-    CanonicalRevert { inner: String },
+    CanonicalRevert {
+        /// The inner error message
+        inner: String,
+    },
+    /// Transaction error on commit with inner details
     #[error("Transaction error on commit: {inner:?}")]
-    CanonicalCommit { inner: String },
-
-    // === tree errors ===
+    CanonicalCommit {
+        /// The inner error message
+        inner: String,
+    },
+    /// Error when appending chain on fork is not possible
     #[error(
         "Appending chain on fork (other_chain_fork:?) is not possible as the tip is {chain_tip:?}"
     )]
-    AppendChainDoesntConnect { chain_tip: BlockNumHash, other_chain_fork: BlockNumHash },
-
+    AppendChainDoesntConnect {
+        /// The tip of the current chain
+        chain_tip: BlockNumHash,
+        /// The fork on the other chain
+        other_chain_fork: BlockNumHash,
+    },
     /// Only used for TestExecutor
     ///
     /// Note: this is not feature gated for convenience.