doc: update some docs related to state

crates/revm/src/db/states/bundle_state.rs

@@ -526,9 +526,11 @@ impl BundleState {
         self.contracts.get(hash).cloned()
     }
 
-    /// Consume `TransitionState` by applying the changes and creating the reverts
+    /// Consume [`TransitionState`] by applying the changes and creating the
+    /// reverts.
     ///
-    /// If [BundleRetention::includes_reverts] is `true`, then the reverts will be retained.
+    /// If [BundleRetention::includes_reverts] is `true`, then the reverts will
+    /// be retained.
     pub fn apply_transitions_and_create_reverts(
         &mut self,
         transitions: TransitionState,

crates/revm/src/db/states/state.rs

@@ -171,6 +171,9 @@ impl<DB: Database> State<DB> {
         }
     }
 
+    /// Get a mutable reference to the [`CacheAccount`] for the given address.
+    /// If the account is not found in the cache, it will be loaded from the
+    /// database and inserted into the cache.
     pub fn load_cache_account(&mut self, address: Address) -> Result<&mut CacheAccount, DB::Error> {
         match self.cache.accounts.entry(address) {
             hash_map::Entry::Vacant(entry) => {
@@ -198,15 +201,15 @@ impl<DB: Database> State<DB> {
     }
 
     // TODO make cache aware of transitions dropping by having global transition counter.
-    /// Takes changeset and reverts from state and replaces it with empty one.
-    /// This will trop pending Transition and any transitions would be lost.
+    /// Takes the [`BundleState`] changeset from the [`State`], replacing it
+    /// with an empty one.
     ///
-    /// NOTE: If either:
-    /// * The [State] has not been built with [StateBuilder::with_bundle_update], or
-    /// * The [State] has a [TransitionState] set to `None` when
-    ///   [State::merge_transitions] is called,
+    /// This will not apply any pending [`TransitionState`]. It is recommended
+    /// to call [`State::merge_transitions`] before taking the bundle.
     ///
-    /// this will panic.
+    /// If the `State` has been built with the
+    /// [`StateBuilder::with_bundle_prestate`] option, the pre-state will be
+    /// taken along with any changes made by [`State::merge_transitions`].
     pub fn take_bundle(&mut self) -> BundleState {
         core::mem::take(&mut self.bundle_state)
     }

crates/revm/src/db/states/transition_state.rs

@@ -9,18 +9,22 @@ pub struct TransitionState {
 }
 
 impl TransitionState {
-    /// Create new transition state with one transition.
+    /// Create new transition state containing one [`TransitionAccount`].
     pub fn single(address: Address, transition: TransitionAccount) -> Self {
         let mut transitions = HashMap::new();
         transitions.insert(address, transition);
         TransitionState { transitions }
     }
 
-    /// Return transition id and all account transitions. Leave empty transition map.
+    /// Take the contents of this [`TransitionState`] and replace it with an
+    /// empty one. See [`core::mem::take`].
     pub fn take(&mut self) -> TransitionState {
         core::mem::take(self)
     }
 
+    /// Add transitions to the transition state. This will insert new
+    /// [`TransitionAccount`]s, or update existing ones via
+    /// [`TransitionAccount::update`].
     pub fn add_transitions(&mut self, transitions: Vec<(Address, TransitionAccount)>) {
         for (address, account) in transitions {
             match self.transitions.entry(address) {