fix[N04] Add additional documentation

contracts/HubPool.sol

@@ -124,6 +124,8 @@ contract HubPool is HubPoolInterface, Testable, Lockable, MultiCaller, Ownable {
     // the full amount of fees entitled to LPs in ~ 7.72 days, just over the standard L2 7 day liveness.
     uint256 public lpFeeRatePerSecond = 1500000000000;
 
+    // Mapping of l1TokenAddress to cumulative unclaimed protocol tokens that can be sent to the protocolFeeCaptureAddress
+    // at any time. This enables the protocol to reallocate some percentage of LP fees elsewhere.
     mapping(address => uint256) public unclaimedAccumulatedProtocolFees;
 
     // Address that captures protocol fees. Accumulated protocol fees can be claimed by this address.

contracts/HubPoolInterface.sol

@@ -16,11 +16,11 @@ interface HubPoolInterface {
         uint256[] bundleLpFees;
         // This array is grouped with the two above, and it represents the amount to send or request back from the
         // SpokePool. If positive, the pool will pay the SpokePool. If negative the SpokePool will pay the HubPool.
-        // There can be arbitrarily complex rebalancing rules defined offchain. This number is only nonzero
-        // when the rules indicate that a rebalancing action should occur. When a rebalance does not occur,
-        // runningBalances for this token should change by the total relays - deposits in this bundle. When a rebalance
-        // does occur, runningBalances should be set to zero for this token and the netSendAmounts should be set to the
-        // previous runningBalances + relays - deposits in this bundle.
+        // There can be arbitrarily complex rebalancing rules defined offchain. This number is only nonzero when the
+        // rules indicate that a rebalancing action should occur. When a rebalance does occur, runningBalances should be
+        // set to zero for this token and the netSendAmounts should be set to the previous runningBalances + relays -
+        // deposits in this bundle. If non-zero then it must be set on the SpokePool's RelayerRefundLeaf amountToReturn
+        // as -1 * this value to indicate if funds are being sent from or to the SpokePool.
         int256[] netSendAmounts;
         // This is only here to be emitted in an event to track a running unpaid balance between the L2 pool and the L1 pool.
         // A positive number indicates that the HubPool owes the SpokePool funds. A negative number indicates that the

contracts/MerkleLib.sol

@@ -14,6 +14,7 @@ library MerkleLib {
      * @param root the merkle root.
      * @param rebalance the rebalance struct.
      * @param proof the merkle proof.
+     * @return bool to signal if the pool rebalance proof correctly shows inclusion of the rebalance within the tree.
      */
     function verifyPoolRebalance(
         bytes32 root,
@@ -28,6 +29,7 @@ library MerkleLib {
      * @param root the merkle root.
      * @param refund the refund struct.
      * @param proof the merkle proof.
+     * @return bool to signal if the relayer refund proof correctly shows inclusion of the refund within the tree.
      */
     function verifyRelayerRefund(
         bytes32 root,
@@ -40,8 +42,9 @@ library MerkleLib {
     /**
      * @notice Verifies that a distribution is contained within a merkle root.
      * @param root the merkle root.
-     * @param slowRelayFulfillment the relayData fulfullment struct.
+     * @param slowRelayFulfillment the relayData fulfillment struct.
      * @param proof the merkle proof.
+     * @return bool to signal if the slow relay's proof correctly shows inclusion of the slow relay within the tree.
      */
     function verifySlowRelayFulfillment(
         bytes32 root,
@@ -95,6 +98,7 @@ library MerkleLib {
      * @param claimedBitMap a simple uint256 mapping in storage used as a bitmap. Uint8 type enforces that index
      * can't be > 255.
      * @param index the index to mark in the bitmap.
+     * @return uint256 representing the modified input claimedBitMap with the index set to true.
      */
     function setClaimed1D(uint256 claimedBitMap, uint8 index) internal pure returns (uint256) {
         return claimedBitMap | (1 << index % 256);

contracts/SpokePoolInterface.sol

@@ -7,8 +7,8 @@ pragma solidity ^0.8.0;
 interface SpokePoolInterface {
     // This leaf is meant to be decoded in the SpokePool to pay out successful relayers.
     struct RelayerRefundLeaf {
-        // This is the amount to return to the HubPool. This occurs when there is a PoolRebalanceLeaf netSendAmount that is
-        // negative. This is just that value inverted.
+        // This is the amount to return to the HubPool. This occurs when there is a PoolRebalanceLeaf netSendAmount that
+        // is negative. This is just that value inverted.
         uint256 amountToReturn;
         // Used to verify that this is being executed on the correct destination chainId.
         uint256 chainId;