fix(docs): use code snippet macros in bridge docs (#2205)

fixes: #2193 Updates the bridge docs code such that it uses code snippets (which can change) rather than having static code
AztecProtocol · Sep 13, 2023 · 0c3a627 · 0c3a627
1 parent dca21c3
commit 0c3a627
Show file tree

Hide file tree

Showing 13 changed files with 117 additions and 295 deletions.
diff --git a/docs/docs/dev_docs/contracts/portals/data_structures.md b/docs/docs/dev_docs/contracts/portals/data_structures.md
@@ -10,14 +10,7 @@ The `DataStructures` are structs that we are using throughout the message infras
 
 An entry for the messageboxes multi-sets. 
 
-```solidity title="DataStructures.sol"
-  struct Entry {
-    uint64 fee;
-    uint32 count;
-    uint32 version;
-    uint32 deadline;
-  }
-```
+#include_code data_structure_entry l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -31,12 +24,7 @@ An entry for the messageboxes multi-sets.
 
 An entity on L1, specifying the address and the chainId for the entity. Used when specifying sender/recipient with an entity that is on L1.
 
-```solidity title="DataStructures.sol"
-  struct L1Actor {
-    address actor;
-    uint256 chainId;
-  }
-```
+#include_code l1_actor l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -48,12 +36,7 @@ An entity on L1, specifying the address and the chainId for the entity. Used whe
 
 An entity on L2, specifying the address and the version for the entity. Used when specifying sender/recipient with an entity that is on L2.
 
-```solidity title="DataStructures.sol"
-  struct L2Actor {
-    bytes32 actor;
-    uint256 version;
-  }
-```
+#include_code l2_actor l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -64,16 +47,7 @@ An entity on L2, specifying the address and the version for the entity. Used whe
 
 A message that is sent from L1 to L2.
 
-```solidity title="DataStructures.sol"
-  struct L1ToL2Msg {
-    L1Actor sender;
-    L2Actor recipient;
-    bytes32 content;
-    bytes32 secretHash;
-    uint32 deadline;
-    uint64 fee;
-  }
-```
+#include_code l1_to_l2_msg l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -88,13 +62,7 @@ A message that is sent from L1 to L2.
 
 A message that is sent from L2 to L1.
 
-```solidity title="DataStructures.sol"
-  struct L2ToL1Msg {
-    DataStructures.L2Actor sender;
-    DataStructures.L1Actor recipient;
-    bytes32 content;
-  }
-```
+#include_code l2_to_l1_msg l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -106,14 +74,7 @@ A message that is sent from L2 to L1.
 
 A snapshot of the registry values.
 
-```solidity title="DataStructures.sol"
-  struct RegistrySnapshot {
-    address rollup;
-    address inbox;
-    address outbox;
-    uint256 blockNumber;
-  }
-```
+#include_code registry_snapshot l1-contracts/src/core/libraries/DataStructures.sol solidity
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |

diff --git a/docs/docs/dev_docs/contracts/portals/inbox.md b/docs/docs/dev_docs/contracts/portals/inbox.md
@@ -10,14 +10,8 @@ The `Inbox` is a contract deployed on L1 that handles message passing from L1 to
 
 Sends a message from L1 to L2.
 
-```solidity
-function sendL2Message(
-  DataStructures.L2Actor memory _recipient,
-  uint32 _deadline,
-  bytes32 _content,
-  bytes32 _secretHash
-) external payable returns (bytes32);
-```
+#include_code send_l1_to_l2_message l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
+
 
 | Name           | Type    | Description |
 | -------------- | ------- | ----------- |
@@ -40,12 +34,7 @@ function sendL2Message(
 ## `cancelL2Message()`
 Cancels a message that has not yet been consumed.
 
-```solidity
-function cancelL2Message(
-  DataStructures.L1ToL2Msg memory _message, 
-  address _feeCollector
-) external returns (bytes32 entryKey);
-```
+#include_code pending_l2_cancel l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
 
 | Name           | Type        | Description |
 | -------------- | -------     | ----------- |
@@ -63,9 +52,8 @@ function cancelL2Message(
 
 Allows the `Rollup` to consume multiple messages in a single transaction.
 
-```solidity
-function batchConsume(bytes32[] memory _entryKeys, address _feeCollector) external;
-```
+#include_code inbox_batch_consume l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
+
 | Name           | Type        | Description |
 | -------------- | -------     | ----------- |
 | `_entryKeys`   | `bytes32[]` | The entry keys (message hashs) to consume |
@@ -84,9 +72,7 @@ Will claim the fees that has accrued to the `msg.sender` from consuming messages
 
 Let the sequencer withdraw fees from the inbox.
 
-```solidity
-function withdrawFees() external;
-```
+#include_code inbox_withdraw_fees l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
 
 #### Edge cases
 
@@ -95,10 +81,7 @@ function withdrawFees() external;
 ## `get()`
 Retrieves the `entry` for a given message. The entry contains fee, number of occurrences, deadline and version information. 
 
-```solidity
-function get(bytes32 _entryKey) 
-  external view returns (DataStructures.Entry memory);
-```
+#include_code inbox_get l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
 
 | Name           | Type        | Description |
 | -------------- | -------     | ----------- |
@@ -112,11 +95,7 @@ function get(bytes32 _entryKey)
 ## `contains()`
 Returns whether the key exists in the inbox.
 
-```solidity
-function contains(
-  bytes32 _entryKey
-) external view returns (bool);
-```
+#include_code inbox_contains l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
 
 | Name           | Type        | Description |
 | -------------- | -------     | ----------- |
@@ -126,11 +105,7 @@ function contains(
 ## `computeEntryKey()`
 Computes the hash of a message.
 
-```solidity
-function computeEntryKey(
-  DataStructures.L1ToL2Msg memory _message
-) external pure returns (bytes32 entryKey);
-```
+#include_code inbox_compute_entry_key l1-contracts/src/core/interfaces/messagebridge/IInbox.sol solidity
 
 | Name           | Type        | Description |
 | -------------- | -------     | ----------- |