Add documentations to document-state/mod module (lambdaclass#894)

* Added comments to document-state/mod.rs

* remove function that was duplicated

---------

Co-authored-by: fannyguthmann <fanny.guthmann@post.idc.ac.il>

src/state/mod.rs

@@ -34,6 +34,7 @@ pub struct BlockInfo {
 }
 
 impl BlockInfo {
+    /// Creates an empty BlockInfo with given sequencer address.
     pub const fn empty(sequencer_address: Address) -> Self {
         BlockInfo {
             block_number: 0, // To do: In cairo-lang, this value is set to -1
@@ -43,6 +44,7 @@ impl BlockInfo {
         }
     }
 
+    /// Validates that the progression from the current block to the next is legal.
     pub const fn validate_legal_progress(
         &self,
         next_block_info: &BlockInfo,
@@ -59,6 +61,7 @@ impl BlockInfo {
     }
 }
 
+/// Provides a default implementation for `BlockInfo`.
 impl Default for BlockInfo {
     fn default() -> Self {
         Self {
@@ -70,13 +73,17 @@ impl Default for BlockInfo {
     }
 }
 
+/// Manages execution resources and keeps track of syscall invocations.
 #[derive(Clone, Debug, Default)]
 pub struct ExecutionResourcesManager {
+    /// Counter for each syscall invocation.
     pub(crate) syscall_counter: HashMap<String, u64>,
+    /// Represents the resources used for Cairo execution.
     pub(crate) cairo_usage: ExecutionResources,
 }
 
 impl ExecutionResourcesManager {
+    /// Initializes a new `ExecutionResourcesManager` with given syscalls and cairo usage.
     pub fn new(syscalls: Vec<String>, cairo_usage: ExecutionResources) -> Self {
         let mut syscall_counter = HashMap::new();
         for syscall in syscalls {
@@ -88,30 +95,38 @@ impl ExecutionResourcesManager {
         }
     }
 
+    /// Increments the syscall counter for a given syscall name by a specified amount.
     pub fn increment_syscall_counter(&mut self, syscall_name: &str, amount: u64) {
         *self
             .syscall_counter
             .entry(syscall_name.to_string())
             .or_default() += amount
     }
 
+    /// Returns the current count for a given syscall name.
     pub fn get_syscall_counter(&self, syscall_name: &str) -> Option<u64> {
         self.syscall_counter
             .get(syscall_name)
             .map(ToOwned::to_owned)
     }
 }
 
+/// Represents a difference in state between two points in time.
 #[derive(Default, Clone, PartialEq, Eq, Debug, Getters)]
 #[getset(get = "pub")]
 pub struct StateDiff {
+    /// Mapping of address to class hash.
     pub(crate) address_to_class_hash: HashMap<Address, ClassHash>,
+    /// Mapping of address to nonce value.
     pub(crate) address_to_nonce: HashMap<Address, Felt252>,
+    /// Mapping of class hash to its compiled representation.
     pub(crate) class_hash_to_compiled_class: HashMap<ClassHash, CompiledClassHash>,
+    /// Represents changes in storage values for different addresses.
     pub(crate) storage_updates: HashMap<Address, HashMap<Felt252, Felt252>>,
 }
 
 impl StateDiff {
+    /// Constructs a new StateDiff.
     pub const fn new(
         address_to_class_hash: HashMap<Address, ClassHash>,
         address_to_nonce: HashMap<Address, Felt252>,
@@ -126,6 +141,7 @@ impl StateDiff {
         }
     }
 
+    /// Creates a `StateDiff` from a cached state.
     pub fn from_cached_state(state_cache: &StateCache) -> Result<Self, StateError> {
         let substracted_maps = &state_cache.storage_writes;
         let storage_updates = to_state_diff_storage_mapping(substracted_maps);
@@ -142,6 +158,7 @@ impl StateDiff {
         })
     }
 
+    /// Converts the current `StateDiff` to a `CachedState`.
     pub fn to_cached_state<T, C>(
         &self,
         state_reader: Arc<T>,
@@ -163,6 +180,7 @@ impl StateDiff {
         Ok(cache_state)
     }
 
+    /// Combines the current state diff with another to form a single cumulative diff.
     pub fn squash(&mut self, other: StateDiff) -> Self {
         self.address_to_class_hash
             .extend(other.address_to_class_hash);
@@ -204,6 +222,7 @@ impl StateDiff {
     }
 }
 
+/// Validates that block progression from a default block to the next one is legal.
 #[test]
 fn test_validate_legal_progress() {
     let first_block = BlockInfo::default();
@@ -232,6 +251,7 @@ mod test {
     use cairo_vm::felt::Felt252;
     use std::{collections::HashMap, sync::Arc};
 
+    /// Ensures that a StateDiff constructed from a CachedState without any updates has no storage updates.
     #[test]
     fn test_from_cached_state_without_updates() {
         let mut state_reader = InMemoryStateReader::default();
@@ -257,6 +277,7 @@ mod test {
         assert_eq!(0, diff.storage_updates.len());
     }
 
+    /// Tests that a new ExecutionResourcesManager starts with zero syscall counters.
     #[test]
     fn execution_resources_manager_should_start_with_zero_syscall_counter() {
         let execution_resources_manager = super::ExecutionResourcesManager::new(
@@ -274,6 +295,7 @@ mod test {
         );
     }
 
+    /// Ensures that incrementing a syscall counter of the `ExecutionResourcesManager` by one works as expected.
     #[test]
     fn execution_resources_manager_should_increment_one_to_the_syscall_counter() {
         let mut execution_resources_manager = super::ExecutionResourcesManager::new(
@@ -293,6 +315,7 @@ mod test {
         );
     }
 
+    /// Verifies that converting a `StateDiff` back to a `CachedState` results in an equivalent `CachedState` to the original.
     #[test]
     fn execution_resources_manager_should_add_syscall_if_not_present() {
         let mut execution_resources_manager = super::ExecutionResourcesManager::default();
@@ -305,6 +328,7 @@ mod test {
         );
     }
 
+    /// Verifies that converting a `StateDiff` back to a `CachedState` results in an equivalent `CachedState` to the original.
     #[test]
     fn state_diff_to_cached_state_should_return_correct_cached_state() {
         let mut state_reader = InMemoryStateReader::default();
@@ -350,6 +374,7 @@ mod test {
         );
     }
 
+    /// Ensures that squashing a StateDiff with itself results in an equivalent StateDiff.
     #[test]
     fn state_diff_squash_with_itself_should_return_same_diff() {
         let mut state_reader = InMemoryStateReader::default();