Updated one third of doc comments

Author: Flatt

crates/context/interface/src/result.rs

@@ -427,8 +427,9 @@ pub enum SuccessReason {
     EofReturnContract,
 }
 
-/// Indicates that the EVM has experienced an exceptional halt. This causes execution to
-/// immediately end with all gas being consumed.
+/// Indicates that the EVM has experienced an exceptional halt.
+///
+/// This causes execution to immediately end with all gas being consumed.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum HaltReason {

crates/context/interface/src/transaction/access_list.rs

@@ -4,9 +4,7 @@ use primitives::{Address, B256};
 /// Access list type is introduced in EIP-2930, and every
 /// transaction after it contains access list.
 ///
-/// Note
-///
-/// Iterator over access list returns account address and storage slot keys that
+/// **Note**: Iterator over access list returns account address and storage slot keys that
 /// are warm loaded before transaction execution.
 ///
 /// Number of account and storage slots is used to calculate initial tx gas cost.

crates/context/interface/src/transaction/eip7702.rs

@@ -12,7 +12,6 @@ pub trait Eip7702Tx: Eip1559Tx {
     /// Returns length of the authorization list.
     ///
     /// # Note
-    ///
     /// Transaction is considered invalid if list is empty.
     fn authorization_list_len(&self) -> usize;
 
@@ -28,10 +27,9 @@ pub trait Eip7702Tx: Eip1559Tx {
 /// Authorization trait.
 #[auto_impl(&, Arc)]
 pub trait Authorization: Clone {
-    /// Authority address.
+    /// Authority address
     ///
     /// # Note
-    ///
     /// Authority signature can be invalid, so this method returns None if the authority
     /// could not be recovered.
     ///
@@ -45,7 +43,6 @@ pub trait Authorization: Clone {
     /// Returns the nonce.
     ///
     /// # Note
-    ///
     /// If nonce is not same as the nonce of the signer account,
     /// the authorization is skipped.
     fn nonce(&self) -> u64;
@@ -78,7 +75,6 @@ impl Authorization for RecoveredAuthorization {
     /// Returns the nonce.
     ///
     /// # Note
-    ///
     /// If nonce is not same as the nonce of the signer account,
     /// authorization is skipped and considered invalidated.
     fn nonce(&self) -> u64 {

crates/context/src/journaled_state.rs

@@ -175,13 +175,12 @@ impl<DB: Database> JournaledStateTrait for JournaledState<DB> {
 }
 
 impl<DB: Database> JournaledState<DB> {
-    /// Create new JournaledState.
+    /// Creates new JournaledState.
     ///
-    /// warm_preloaded_addresses is used to determine if address is considered warm loaded.
+    /// `warm_preloaded_addresses` is used to determine if address is considered warm loaded.
     /// In ordinary case this is precompile or beneficiary.
     ///
     /// # Note
-    ///
     /// This function will journal state after Spurious Dragon fork.
     /// And will not take into account if account is not existing or empty.
     pub fn new(spec: SpecId, database: DB) -> JournaledState<DB> {
@@ -259,8 +258,9 @@ impl<DB: Database> JournaledState<DB> {
         account.info.code = Some(code);
     }
 
-    /// use it only if you know that acc is warm
-    /// Assume account is warm
+    /// Use it only if you know that acc is warm.
+    ///
+    /// Assume account is warm.
     #[inline]
     pub fn set_code(&mut self, address: Address, code: Bytecode) {
         let hash = code.hash_slow();
@@ -336,7 +336,7 @@ impl<DB: Database> JournaledState<DB> {
         Ok(None)
     }
 
-    /// Create account or return false if collision is detected.
+    /// Creates account or returns false if collision is detected.
     ///
     /// There are few steps done:
     /// 1. Make created account warm loaded (AccessList) and this should
@@ -421,7 +421,7 @@ impl<DB: Database> JournaledState<DB> {
         Ok(checkpoint)
     }
 
-    /// Revert all changes that happened in given journal entries.
+    /// Reverts all changes that happened in given journal entries.
     #[inline]
     fn journal_revert(
         state: &mut EvmState,
@@ -540,7 +540,7 @@ impl<DB: Database> JournaledState<DB> {
         checkpoint
     }
 
-    /// Commit the checkpoint.
+    /// Commits the checkpoint.
     #[inline]
     pub fn checkpoint_commit(&mut self) {
         self.depth -= 1;
@@ -572,14 +572,14 @@ impl<DB: Database> JournaledState<DB> {
         self.journal.truncate(checkpoint.journal_i);
     }
 
-    /// Performances selfdestruct action.
+    /// Performs selfdestruct action.
     /// Transfers balance from address to target. Check if target exist/is_cold
     ///
     /// Note: Balance will be lost if address and target are the same BUT when
     /// current spec enables Cancun, this happens only when the account associated to address
     /// is created in the same tx
     ///
-    /// references:
+    /// # References:
     ///  * <https://github.com/ethereum/go-ethereum/blob/141cd425310b503c5678e674a8c3872cf46b7086/core/vm/instructions.go#L832-L833>
     ///  * <https://github.com/ethereum/go-ethereum/blob/141cd425310b503c5678e674a8c3872cf46b7086/core/state/statedb.go#L449>
     ///  * <https://eips.ethereum.org/EIPS/eip-6780>
@@ -675,7 +675,7 @@ impl<DB: Database> JournaledState<DB> {
         Ok(account)
     }
 
-    /// load account into memory. return if it is cold or warm accessed
+    /// Loads account into memory. return if it is cold or warm accessed
     #[inline]
     pub fn load_account(&mut self, address: Address) -> Result<StateLoad<&mut Account>, DB::Error> {
         self.load_account_optional(address, false)
@@ -707,7 +707,7 @@ impl<DB: Database> JournaledState<DB> {
         self.load_account_optional(address, true)
     }
 
-    /// Loads code.
+    /// Loads code
     #[inline]
     pub fn load_account_optional(
         &mut self,
@@ -762,7 +762,7 @@ impl<DB: Database> JournaledState<DB> {
         Ok(load)
     }
 
-    /// Load storage slot
+    /// Loads storage slot.
     ///
     /// # Panics
     ///
@@ -805,11 +805,10 @@ impl<DB: Database> JournaledState<DB> {
     }
 
     /// Stores storage slot.
-    /// And returns (original,present,new) slot value.
     ///
-    /// Note:
+    /// And returns (original,present,new) slot value.
     ///
-    /// account should already be present in our state.
+    /// **Note**: Account should already be present in our state.
     #[inline]
     pub fn sstore(
         &mut self,
@@ -909,7 +908,7 @@ impl<DB: Database> JournaledState<DB> {
         }
     }
 
-    /// push log into subroutine
+    /// Pushes log into subroutine.
     #[inline]
     pub fn log(&mut self, log: Log) {
         self.logs.push(log);

crates/database/interface/src/async_db.rs

@@ -98,7 +98,7 @@ impl<T> WrapDatabaseAsync<T> {
         Some(Self { db, rt })
     }
 
-    /// Wrap a [DatabaseAsync] or [DatabaseAsyncRef] instance, with a runtime.
+    /// Wraps a [DatabaseAsync] or [DatabaseAsyncRef] instance, with a runtime.
     ///
     /// Refer to [tokio::runtime::Builder] on how to create a runtime if you are in synchronous world.
     /// If you are already using something like [tokio::main], call [WrapDatabaseAsync::new] instead.
@@ -107,7 +107,7 @@ impl<T> WrapDatabaseAsync<T> {
         Self { db, rt }
     }
 
-    /// Wrap a [DatabaseAsync] or [DatabaseAsyncRef] instance, with a runtime handle.
+    /// Wraps a [DatabaseAsync] or [DatabaseAsyncRef] instance, with a runtime handle.
     ///
     /// This generally allows you to pass any valid runtime handle, refer to [tokio::runtime::Handle] on how
     /// to obtain a handle. If you are already in asynchronous world, like [tokio::main], use [WrapDatabaseAsync::new]

crates/database/interface/src/lib.rs

@@ -36,16 +36,16 @@ pub trait Database {
     type Error: DBErrorMarker;
     //type Bytecode: BytecodeTrait;
 
-    /// Get basic account information.
+    /// Gets basic account information.
     fn basic(&mut self, address: Address) -> Result<Option<AccountInfo>, Self::Error>;
 
-    /// Get account code by its hash.
+    /// Gets account code by its hash.
     fn code_by_hash(&mut self, code_hash: B256) -> Result<Bytecode, Self::Error>;
 
-    /// Get storage value of address at index.
+    /// Gets storage value of address at index.
     fn storage(&mut self, address: Address, index: U256) -> Result<U256, Self::Error>;
 
-    /// Get block hash by block number.
+    /// Gets block hash by block number.
     fn block_hash(&mut self, number: u64) -> Result<B256, Self::Error>;
 }
 
@@ -67,16 +67,16 @@ pub trait DatabaseRef {
     /// The database error type.
     type Error: DBErrorMarker;
 
-    /// Get basic account information.
+    /// Gets basic account information.
     fn basic_ref(&self, address: Address) -> Result<Option<AccountInfo>, Self::Error>;
 
-    /// Get account code by its hash.
+    /// Gets account code by its hash.
     fn code_by_hash_ref(&self, code_hash: B256) -> Result<Bytecode, Self::Error>;
 
-    /// Get storage value of address at index.
+    /// Gets storage value of address at index.
     fn storage_ref(&self, address: Address, index: U256) -> Result<U256, Self::Error>;
 
-    /// Get block hash by block number.
+    /// Gets block hash by block number.
     fn block_hash_ref(&self, number: u64) -> Result<B256, Self::Error>;
 }
 

crates/database/src/alloydb.rs

@@ -35,7 +35,7 @@ pub struct AlloyDB<T: Transport + Clone, N: Network, P: Provider<T, N>> {
 }
 
 impl<T: Transport + Clone, N: Network, P: Provider<T, N>> AlloyDB<T, N, P> {
-    /// Create a new AlloyDB instance, with a [Provider] and a block.
+    /// Creates a new AlloyDB instance, with a [Provider] and a block.
     pub fn new(provider: P, block_number: BlockId) -> Self {
         Self {
             provider,
@@ -44,7 +44,7 @@ impl<T: Transport + Clone, N: Network, P: Provider<T, N>> AlloyDB<T, N, P> {
         }
     }
 
-    /// Set the block number on which the queries will be based on.
+    /// Sets the block number on which the queries will be based on.
     pub fn set_block_number(&mut self, block_number: BlockId) {
         self.block_number = block_number;
     }

crates/database/src/in_memory_db.rs

@@ -39,7 +39,7 @@ impl<ExtDB: Default> Default for CacheDB<ExtDB> {
 }
 
 impl<ExtDb> CacheDB<CacheDB<ExtDb>> {
-    /// Flatten a nested cache by applying the outer cache to the inner cache.
+    /// Flattens a nested cache by applying the outer cache to the inner cache.
     ///
     /// The behavior is as follows:
     /// - Accounts are overridden with outer accounts
@@ -62,14 +62,14 @@ impl<ExtDb> CacheDB<CacheDB<ExtDb>> {
         inner
     }
 
-    /// Discard the outer cache and return the inner cache.
+    /// Discards the outer cache and return the inner cache.
     pub fn discard_outer(self) -> CacheDB<ExtDb> {
         self.db
     }
 }
 
 impl<ExtDB> CacheDB<ExtDB> {
-    /// Create a new cache with the given external database.
+    /// Creates a new cache with the given external database.
     pub fn new(db: ExtDB) -> Self {
         let mut contracts = HashMap::default();
         contracts.insert(KECCAK_EMPTY, Bytecode::default());
@@ -104,13 +104,13 @@ impl<ExtDB> CacheDB<ExtDB> {
         }
     }
 
-    /// Insert account info but not override storage
+    /// Inserts account info but not override storage
     pub fn insert_account_info(&mut self, address: Address, mut info: AccountInfo) {
         self.insert_contract(&mut info);
         self.accounts.entry(address).or_default().info = info;
     }
 
-    /// Wrap the cache in a [CacheDB], creating a nested cache.
+    /// Wraps the cache in a [CacheDB], creating a nested cache.
     pub fn nest(self) -> CacheDB<Self> {
         CacheDB::new(self)
     }
@@ -135,7 +135,7 @@ impl<ExtDB: DatabaseRef> CacheDB<ExtDB> {
         }
     }
 
-    /// insert account storage without overriding account info
+    /// Inserts account storage without overriding account info
     pub fn insert_account_storage(
         &mut self,
         address: Address,
@@ -147,7 +147,7 @@ impl<ExtDB: DatabaseRef> CacheDB<ExtDB> {
         Ok(())
     }
 
-    /// replace account storage without overriding account info
+    /// Replaces account storage without overriding account info
     pub fn replace_account_storage(
         &mut self,
         address: Address,
@@ -329,7 +329,7 @@ pub struct DbAccount {
     pub info: AccountInfo,
     /// If account is selfdestructed or newly created, storage will be cleared.
     pub account_state: AccountState,
-    /// storage slots
+    /// Storage slots
     pub storage: HashMap<U256, U256>,
 }
 

crates/database/src/states/account_status.rs

@@ -198,15 +198,15 @@ impl AccountStatus {
     /// Transition to other state while preserving invariance of this state.
     ///
     /// It this account was Destroyed and other account is not:
-    /// we should mark extended account as destroyed too.
-    /// and as other account had some changes, extended account
-    /// should be marked as DestroyedChanged.
+    /// - We should mark extended account as destroyed too.
+    /// - And as other account had some changes, extended account
+    ///   should be marked as DestroyedChanged.
     ///
     /// If both account are not destroyed and if this account is in memory:
-    /// this means that extended account is in memory too.
+    /// - This means that extended account is in memory too.
     ///
     /// Otherwise, if both are destroyed or other is destroyed:
-    /// set other status to extended account.
+    /// -  Sets other status to extended account.
     pub fn transition(&mut self, other: Self) {
         *self = match (self.was_destroyed(), other.was_destroyed()) {
             (true, false) => Self::DestroyedChanged,

crates/database/src/states/bundle_account.rs

@@ -11,6 +11,7 @@ use state::AccountInfo;
 /// Status is needed as to know from what state we are applying the TransitionAccount.
 ///
 /// Original account info is needed to know if there was a change.
+///
 /// Same thing for storage with original value.
 ///
 /// On selfdestruct storage original value is ignored.
@@ -46,6 +47,7 @@ impl BundleAccount {
     }
 
     /// The approximate size of changes needed to store this account.
+    ///
     /// `1 + storage_len`
     pub fn size_hint(&self) -> usize {
         1 + self.storage.len()
@@ -127,7 +129,9 @@ impl BundleAccount {
     }
 
     /// Update to new state and generate AccountRevert that if applied to new state will
-    /// revert it to previous state. If no revert is present, update is noop.
+    /// revert it to previous state.
+    ///
+    /// If no revert is present, update is noop.
     pub fn update_and_create_revert(
         &mut self,
         transition: TransitionAccount,