mock_call appendix revamp

docs/src/SUMMARY.md

@@ -46,6 +46,7 @@
 * [Cheatcodes Reference](appendix/cheatcodes.md)
  * [CheatTarget](appendix/cheatcodes/cheat_target.md)
  * [CheatSpan](appendix/cheatcodes/cheat_span.md)
+ * [mock](appendix/cheatcodes/mock_call.md)
  * [caller_address](appendix/cheatcodes/caller_address/README.md)
  * [prank](appendix/cheatcodes/caller_address/prank.md)
  * [start_prank](appendix/cheatcodes/caller_address/start_prank.md)
@@ -66,10 +67,6 @@
  * [spoof](appendix/cheatcodes/tx_info/spoof.md)
  * [start_spoof](appendix/cheatcodes/tx_info/start_spoof.md)
  * [stop_spoof](appendix/cheatcodes/tx_info/stop_spoof.md)
- * [mock](appendix/cheatcodes/mock/README.md)
- * [mock_call](appendix/cheatcodes/mock/mock_call.md)
- * [start_mock_call](appendix/cheatcodes/mock/start_mock_call.md)
- * [stop_mock_call](appendix/cheatcodes/mock/stop_mock_call.md)
  * [get_class_hash](appendix/cheatcodes/get_class_hash.md)
  * [replace_bytecode](appendix/cheatcodes/replace_bytecode.md)
  * [l1_handler_execute](appendix/cheatcodes/l1_handler_execute.md)

docs/src/appendix/cheatcodes.md

@@ -17,9 +17,9 @@
 - [`spoof`](cheatcodes/tx_info/spoof.md) - changes the transaction context for contracts, for a number of calls
 - [`start_spoof`](cheatcodes/tx_info/start_spoof.md) - changes the transaction context for contracts
 - [`stop_spoof`](cheatcodes/tx_info/stop_spoof.md) - cancels the `spoof` / `start_spoof` for contracts
-- [`mock_call`](cheatcodes/mock/mock_call.md) - mocks a number of contract calls to an entry point
-- [`start_mock_call`](cheatcodes/mock/start_mock_call.md) - mocks contract call to an entry point
-- [`stop_mock_call`](cheatcodes/mock/stop_mock_call.md) - cancels the `mock_call` / `start_mock_call` for an entry point
+- [`mock_call`](cheatcodes/mock_call.md#mock_call) - mocks a number of contract calls to an entry point
+- [`start_mock_call`](cheatcodes/mock_call.md#start_mock_call) - mocks contract call to an entry point
+- [`stop_mock_call`](cheatcodes/mock_call.md#stop_mock_call) - cancels the `mock_call` / `start_mock_call` for an entry point
 - [`get_class_hash`](cheatcodes/get_class_hash.md) - retrieves a class hash of a contract
 - [`replace_bytecode`](cheatcodes/replace_bytecode.md) - replace the class hash of a contract
 - [`l1_handler_execute`](cheatcodes/l1_handler_execute.md) - executes a `#[l1_handler]` function to mock a message arriving from Ethereum

docs/src/appendix/cheatcodes/mock_call.md

@@ -0,0 +1,30 @@
+# `mock_call`
+
+Cheatcodes mocking contract entry point calls:
+
+## `mock_call`
+> `fn mock_call<T, impl TSerde: serde::Serde<T>, impl TDestruct: Destruct<T>>(
+> contract_address: ContractAddress, function_selector: felt252, ret_data: T, n_times: u32
+> )`
+
+Mocks contract call to a `function_selector` of a contract at the given address, for `n_times` first calls that are made 
+to the contract. 
+A call to function `function_selector` will return data provided in `ret_data` argument. 
+An address with no contract can be mocked as well. 
+An entrypoint that is not present on the deployed contract is also possible to mock.
+Note that the function is not meant for mocking internal calls - it works only for contract entry points.
+
+## `start_mock_call`
+> `fn start_mock_call<T, impl TSerde: serde::Serde<T>, impl TDestruct: Destruct<T>>(
+> contract_address: ContractAddress, function_selector: felt252, ret_data: T
+> )`
+
+Mocks contract call to a `function_selector` of a contract at the given address, indefinitely.
+See `mock_call` for comprehensive definition of how it can be used.
+
+
+## `stop_mock_call`
+
+> `fn stop_mock_call(contract_address: ContractAddress, function_selector: felt252)`
+
+Cancels the `mock_call` / `start_mock_call` for the function `function_selector` of a contract at the given address.

snforge_std/src/cheatcodes.cairo

@@ -110,6 +110,17 @@ fn stop_elect(target: CheatTarget) {
  handle_cheatcode(cheatcode::<'stop_elect'>(inputs.span()));
 }
 
+
+/// Mocks contract call to a `function_selector` of a contract at the given address, for `n_times` first calls that are made
+/// to the contract.
+/// A call to function `function_selector` will return data provided in `ret_data` argument.
+/// An address with no contract can be mocked as well.
+/// An entrypoint that is not present on the deployed contract is also possible to mock.
+/// Note that the function is not meant for mocking internal calls - it works only for contract entry points.
+/// - `contract_address` - target contract address
+/// - `function_selector` - selector of the function in a contract at the `contract_address` that will be mocked
+/// - `ret_data` - data to return by the function `function_selector`
+/// - `n_times` - number of calls to mock the function for
 fn mock_call<T, impl TSerde: core::serde::Serde<T>, impl TDestruct: Destruct<T>>(
  contract_address: ContractAddress, function_selector: felt252, ret_data: T, n_times: u32
 ) {
@@ -128,6 +139,13 @@ fn mock_call<T, impl TSerde: core::serde::Serde<T>, impl TDestruct: Destruct<T>>
  handle_cheatcode(cheatcode::<'mock_call'>(inputs.span()));
 }
 
+
+
+/// Mocks contract call to a `function_selector` of a contract at the given address, indefinitely.
+/// See `mock_call` for comprehensive definition of how it can be used.
+/// - `contract_address` - target contract address
+/// - `function_selector` - selector of the function in a contract at the `contract_address` that will be mocked
+/// - `ret_data` - data to return by the function `function_selector`
 fn start_mock_call<T, impl TSerde: core::serde::Serde<T>, impl TDestruct: Destruct<T>>(
  contract_address: ContractAddress, function_selector: felt252, ret_data: T
 ) {
@@ -144,6 +162,9 @@ fn start_mock_call<T, impl TSerde: core::serde::Serde<T>, impl TDestruct: Destru
  handle_cheatcode(cheatcode::<'mock_call'>(inputs.span()));
 }
 
+/// Cancels the `mock_call` / `start_mock_call` for the function `function_selector` of a contract at the given address.
+/// - `contract_address` - target contract address
+/// - `function_selector` - selector of the function
 fn stop_mock_call(contract_address: ContractAddress, function_selector: felt252) {
  let contract_address_felt: felt252 = contract_address.into();
  handle_cheatcode(