block_timestamp appendix revamp (#2019)

<!-- Reference any GitHub issues resolved by this PR -->

Related: #1439

## Introduced changes

<!-- A brief description of the changes -->

-

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

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)
+ * [block_timestamp](appendix/cheatcodes/block_timestamp.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)
@@ -58,10 +59,6 @@
  * [roll](appendix/cheatcodes/block_number/roll.md)
  * [start_roll](appendix/cheatcodes/block_number/start_roll.md)
  * [stop_roll](appendix/cheatcodes/block_number/stop_roll.md)
- * [block_timestamp](appendix/cheatcodes/block_timestamp/README.md)
- * [warp](appendix/cheatcodes/block_timestamp/warp.md)
- * [start_warp](appendix/cheatcodes/block_timestamp/start_warp.md)
- * [stop_warp](appendix/cheatcodes/block_timestamp/stop_warp.md)
  * [tx_info](appendix/cheatcodes/tx_info/README.md)
  * [spoof](appendix/cheatcodes/tx_info/spoof.md)
  * [start_spoof](appendix/cheatcodes/tx_info/start_spoof.md)

docs/src/appendix/cheatcodes.md

@@ -8,9 +8,9 @@
 - [`roll`](cheatcodes/block_number/roll.md) - changes the block number for contracts, for a number of calls
 - [`start_roll`](cheatcodes/block_number/start_roll.md) - changes the block number for contracts
 - [`stop_roll`](cheatcodes/block_number/stop_roll.md) - cancels the `roll` / `start_roll` for contracts
-- [`warp`](cheatcodes/block_timestamp/warp.md) - changes the block timestamp for contracts, for a number of calls
-- [`start_warp`](cheatcodes/block_timestamp/start_warp.md) - changes the block timestamp for contracts
-- [`stop_warp`](cheatcodes/block_timestamp/stop_warp.md) - cancels the `warp` / `start_warp` for contracts
+- [`warp`](cheatcodes/block_timestamp#warp) - changes the block timestamp for contracts, for a number of calls
+- [`start_warp`](cheatcodes/block_timestamp#start_warp) - changes the block timestamp for contracts
+- [`stop_warp`](cheatcodes/block_timestamp#stop_warp) - cancels the `warp` / `start_warp` for contracts
 - [`elect`](cheatcodes/sequencer_address/elect.md) - changes the sequencer address for contracts, for a number of calls
 - [`start_elect`](cheatcodes/sequencer_address/start_elect.md) - changes the sequencer address for contracts
 - [`stop_elect`](cheatcodes/sequencer_address/stop_elect.md) - cancels the `elect` / `start_elect` for contracts

docs/src/appendix/cheatcodes/block_timestamp.md

@@ -0,0 +1,20 @@
+# `block_timestamp`
+
+Cheatcodes modifying `block_timestamp`:
+
+## `warp`
+
+> `fn warp(target: CheatTarget, block_timestamp: u64, span: CheatSpan)`
+
+Changes the block timestamp for the given target and span.
+
+## `start_warp`
+> `fn start_warp(target: CheatTarget, block_timestamp: u64)`
+
+Changes the block timestamp for the given target.
+
+## `stop_warp`
+
+> `fn stop_warp(target: CheatTarget)`
+
+Cancels the `warp` / `start_warp` for the given target.

snforge_std/src/cheatcodes.cairo

@@ -70,6 +70,10 @@ fn stop_prank(target: CheatTarget) {
  handle_cheatcode(cheatcode::<'stop_prank'>(inputs.span()));
 }
 
+/// Changes the block timestamp for the given target and span.
+/// - `target` - instance of `CheatTarget` specifying which contracts to warp
+/// - `block_timestamp` - block timestamp to be set
+/// - `span` - instance of `CheatSpan` specifying the number of target calls with the cheat applied
 fn warp(target: CheatTarget, block_timestamp: u64, span: CheatSpan) {
  validate_cheat_target_and_span(@target, @span);
 
@@ -80,10 +84,15 @@ fn warp(target: CheatTarget, block_timestamp: u64, span: CheatSpan) {
  handle_cheatcode(cheatcode::<'warp'>(inputs.span()));
 }
 
+/// Changes the block timestamp for the given target.
+/// - `target` - instance of `CheatTarget` specifying which contracts to warp
+/// - `block_timestamp` - block timestamp to be set
 fn start_warp(target: CheatTarget, block_timestamp: u64) {
  warp(target, block_timestamp, CheatSpan::Indefinite);
 }
 
+/// Cancels the `warp` / `start_warp` for the given target.
+/// - `target` - instance of `CheatTarget` specifying which contracts to stop warping
 fn stop_warp(target: CheatTarget) {
  let mut inputs = array![];
  target.serialize(ref inputs);