Use NatSpec for ITokenBridge events and errors

contracts/contracts/ZkEvmV2.sol

@@ -7,7 +7,7 @@ import { L1MessageServiceV1 } from "./messageService/l1/v1/L1MessageServiceV1.so
 import { IZkEvmV2 } from "./interfaces/l1/IZkEvmV2.sol";
 import { IPlonkVerifier } from "./interfaces/l1/IPlonkVerifier.sol";
 /**
- * @title Contract to manage cross-chain messaging on L1 and rollup proving.
+ * @title Contract to manage cross-chain L1 rollup proving.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */
@@ -53,12 +53,11 @@ abstract contract ZkEvmV2 is Initializable, AccessControlUpgradeable, L1MessageS
         assembly {
           let dataOffset := add(result, 0x20)
 
-          // Store the modified first 32 bytes back into memory overwriting the location after having swapped out the selector
+          // Store the modified first 32 bytes back into memory overwriting the location after having swapped out the selector.
           mstore(
             dataOffset,
             or(
-              // InvalidProofOrProofVerificationRanOutOfGas(string) = 0xca389c44bf373a5a506ab5a7d8a53cb0ea12ba7c5872fd2bc4a0e31614c00a85
-              // Using the selector from a bytes4 variable and shl results in 0x00000000
+              // InvalidProofOrProofVerificationRanOutOfGas(string) = 0xca389c44bf373a5a506ab5a7d8a53cb0ea12ba7c5872fd2bc4a0e31614c00a85.
               shl(224, 0xca389c44),
               and(mload(dataOffset), 0x00000000ffffffffffffffffffffffffffffffffffffffffffffffffffffffff)
             )

contracts/contracts/interfaces/IPauseManager.sol

@@ -22,6 +22,7 @@ interface IPauseManager {
    * @notice Enum defining the different types of pausing.
    * @dev The pause types are used to pause and unpause specific functionality.
    * @dev The UNUSED pause type is used as a default value to avoid accidental general pausing.
+   * @dev Enums are uint8 by default.
    */
   enum PauseType {
     UNUSED,

contracts/contracts/interfaces/l1/IL1MessageManager.sol

@@ -48,6 +48,7 @@ interface IL1MessageManager {
   /**
    * @notice Checks if the L2->L1 message is claimed or not.
    * @param _messageNumber The message number on L2.
+   * @return Bool indicating claimed or not.
    */
   function isMessageClaimed(uint256 _messageNumber) external view returns (bool);
 }

contracts/contracts/interfaces/l1/IL1MessageManagerV1.sol

@@ -2,7 +2,7 @@
 pragma solidity 0.8.26;
 
 /**
- * @title L1 Message manager V1 interface for pre-existing functions, events and errors.
+ * @title L1 Message manager V1 interface for pre-existing errors.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */

contracts/contracts/interfaces/l1/ILineaRollup.sol

@@ -12,9 +12,9 @@ import { IPermissionsManager } from "../../interfaces/IPermissionsManager.sol";
 interface ILineaRollup {
   /**
    * @notice Initialization data structure for the LineaRollup contract.
-   * @param initialStateRootHash The initial state root hash at migration used for proof verification.
-   * @param initialL2BlockNumber The initial block number at migration.
-   * @param genesisTimestamp The L2 genesis timestamp for first finalization.
+   * @param initialStateRootHash The initial state root hash at initialization used for proof verification.
+   * @param initialL2BlockNumber The initial block number at initialization.
+   * @param genesisTimestamp The L2 genesis timestamp for first initialization.
    * @param defaultVerifier The default verifier for rollup proofs.
    * @param rateLimitPeriodInSeconds The period in which withdrawal amounts and fees will be accumulated.
    * @param rateLimitAmountInWei The limit allowed for withdrawing in the rate limit period.
@@ -40,11 +40,11 @@ interface ILineaRollup {
 
   /**
    * @notice Supporting data for compressed calldata submission including compressed data.
-   * @dev finalStateRootHash is used to set state root at the end of the data.
+   * @dev finalStateRootHash is used to set state root hash at the end of the data.
    * @dev firstBlockInData is the first block that is included in the data submitted.
    * @dev finalBlockInData is the last block that is included in the data submitted.
    * @dev snarkHash is the computed hash for compressed data (using a SNARK-friendly hash function) that aggregates per data submission to be used in public input.
-   * @dev compressedData is the compressed transaction data. It contains ordered data for each L2 block - l2Timestamps, the encoded txData.
+   * @dev compressedData is the compressed transaction data. It contains ordered data for each L2 block - l2Timestamps, the encoded transaction data.
    */
   struct SubmissionDataV2 {
     bytes32 finalStateRootHash;
@@ -190,9 +190,9 @@ interface ILineaRollup {
    * @notice Emitted when L2 blocks have been finalized on L1.
    * @param startBlockNumber The indexed L2 block number indicating which block the finalization the data starts from.
    * @param endBlockNumber The indexed L2 block number indicating which block the finalization the data ends on.
-   * @param shnarf The shnarf being set as currentFinalizedShnarf in the current finalization.
-   * @param parentStateRootHash The indexed parent L2 state root hash that the current finalization starts from.
-   * @param finalStateRootHash The indexed L2 state root hash that the current finalization ends on.
+   * @param shnarf The indexed shnarf being set as currentFinalizedShnarf in the current finalization.
+   * @param parentStateRootHash The parent L2 state root hash that the current finalization starts from.
+   * @param finalStateRootHash The L2 state root hash that the current finalization ends on.
    */
   event DataFinalizedV3(
     uint256 indexed startBlockNumber,

contracts/contracts/interfaces/l2/IL2MessageManager.sol

@@ -9,7 +9,7 @@ pragma solidity 0.8.19;
 interface IL2MessageManager {
   /**
    * @notice Emitted after all messages are anchored on L2 and the latest message index and rolling hash stored.
-   * @param messageNumber The unique L1 computed indexed message number for the message.
+   * @param messageNumber The indexed unique L1 computed indexed message number for the message.
    * @param rollingHash The indexed L1 rolling hash computed for the current message number.
    * @dev NB: This event is used to provide data to the rollup. The last messageNumber and rollingHash,
    * emitted in a rollup will be used in the public input for validating the L1->L2 messaging state transition.
@@ -18,7 +18,8 @@ interface IL2MessageManager {
 
   /**
    * @dev Emitted when the service switches over to a new version.
-   * @dev This is currently not in use, but left for future migrations and for existing consumers.
+   * @dev This is currently not in use, but left for existing consumers.
+   * @param version The indexed version.
    */
   event ServiceVersionMigrated(uint256 indexed version);
 

contracts/contracts/interfaces/l2/IL2MessageServiceV1.sol

@@ -9,6 +9,7 @@ pragma solidity 0.8.19;
 interface IL2MessageServiceV1 {
   /**
    * @notice The Fee Manager sets a minimum fee to address DOS protection.
+   * @dev MINIMUM_FEE_SETTER_ROLE is required to set the minimum fee.
    * @param _feeInWei New minimum fee in Wei.
    */
   function setMinimumFee(uint256 _feeInWei) external;

contracts/contracts/lib/L2MessageServicePauseManager.sol

@@ -4,7 +4,7 @@ pragma solidity >=0.8.19 <=0.8.26;
 import { PauseManager } from "./PauseManager.sol";
 
 /**
- * @title Contract to manage cross-chain function pausing for LineaRollup.
+ * @title Contract to manage cross-chain function pausing roles for the L2 Message Service.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */

contracts/contracts/lib/LineaRollupPauseManager.sol

@@ -4,7 +4,7 @@ pragma solidity >=0.8.19 <=0.8.26;
 import { PauseManager } from "./PauseManager.sol";
 
 /**
- * @title Contract to manage cross-chain function pausing for LineaRollup.
+ * @title Contract to manage cross-chain function pausing roles for the LineaRollup.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */

contracts/contracts/lib/TokenBridgePauseManager.sol

@@ -4,7 +4,7 @@ pragma solidity >=0.8.19 <=0.8.26;
 import { PauseManager } from "./PauseManager.sol";
 
 /**
- * @title Contract to manage cross-chain function pausing for LineaRollup.
+ * @title Contract to manage cross-chain function pausing roles for the Token Bridge.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */

contracts/contracts/messageService/MessageServiceBase.sol

@@ -65,7 +65,7 @@ abstract contract MessageServiceBase is Initializable, IGenericErrors {
 
   /**
    * @notice Initializes the message service
-   * @dev Must be initialized in the initialize function of the main contract or constructor
+   * @dev Must be initialized in the initialize function of the main contract or constructor.
    * @param _messageService The message service address, cannot be empty.
    */
   function __MessageServiceBase_init(address _messageService) internal onlyInitializing {

contracts/contracts/messageService/l2/v1/L2MessageServiceV1.sol

@@ -148,6 +148,7 @@ abstract contract L2MessageServiceV1 is
 
   /**
    * @notice The Fee Manager sets a minimum fee to address DOS protection.
+   * @dev MINIMUM_FEE_SETTER_ROLE is required to set the minimum fee.
    * @param _feeInWei New minimum fee in Wei.
    */
   function setMinimumFee(uint256 _feeInWei) external onlyRole(MINIMUM_FEE_SETTER_ROLE) {

contracts/contracts/messageService/lib/MessageHashing.sol

@@ -2,14 +2,14 @@
 pragma solidity >=0.8.19 <=0.8.26;
 
 /**
- * @title Library to hash messages.
+ * @title Library to hash cross-chain messages.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */
 library MessageHashing {
   /**
    * @notice Hashes messages using assembly for efficiency.
-   * @dev Adding 0x00000000000000000000000000000000000000000000000000000000000000c0 is to indicate the calldata offset.
+   * @dev Adding 0xc0 is to indicate the calldata offset relative to the memory being added to.
    * @dev If the calldata is not modulus 32, the extra bit needs to be added on at the end else the hash is wrong.
    * @param _from The from address.
    * @param _to The to address.
@@ -33,7 +33,7 @@ library MessageHashing {
       mstore(add(mPtr, 0x40), _fee)
       mstore(add(mPtr, 0x60), _valueSent)
       mstore(add(mPtr, 0x80), _messageNumber)
-      mstore(add(mPtr, 0xa0), 0x00000000000000000000000000000000000000000000000000000000000000c0)
+      mstore(add(mPtr, 0xa0), 0xc0)
       mstore(add(mPtr, 0xc0), _calldata.length)
       let rem := mod(_calldata.length, 0x20)
       let extra := 0

contracts/contracts/tokenBridge/CustomBridgedToken.sol

@@ -5,7 +5,7 @@ import { BridgedToken } from "./BridgedToken.sol";
 
 /**
  * @title Custom BridgedToken Contract
- * @notice Custom ERC20 token manually deployed for the Linea TokenBridge
+ * @notice Custom ERC20 token manually deployed for the Linea TokenBridge.
  */
 contract CustomBridgedToken is BridgedToken {
   function initializeV2(

contracts/contracts/tokenBridge/interfaces/ITokenBridge.sol

@@ -5,7 +5,7 @@ import { IPauseManager } from "../../interfaces/IPauseManager.sol";
 import { IPermissionsManager } from "../../interfaces/IPermissionsManager.sol";
 
 /**
- * @title Interface declaring Canonical Token Bridge functions, events and errors.
+ * @title Interface declaring Canonical Token Bridge struct, functions, events and errors.
  * @author ConsenSys Software Inc.
  * @custom:security-contact [email protected]
  */
@@ -34,48 +34,184 @@ interface ITokenBridge {
     IPauseManager.PauseTypeRole[] unpauseTypeRoles;
   }
 
+  /**
+   * @notice Emitted when the token address is reserved.
+   * @param token The indexed token address.
+   */
   event TokenReserved(address indexed token);
+
+  /**
+   * @notice Emitted when the token address reservation is removed.
+   * @param token The indexed token address.
+   */
   event ReservationRemoved(address indexed token);
+
+  /**
+   * @notice Emitted when the custom token address is set.
+   * @param nativeToken The indexed nativeToken token address.
+   * @param customContract The indexed custom contract address.
+   * @param setBy The indexed address of who set the custom contract.
+   */
   event CustomContractSet(address indexed nativeToken, address indexed customContract, address indexed setBy);
-  /// @dev DEPRECATED in favor of BridgingInitiatedV2.
+
+  /**
+   * @notice Emitted when token bridging is initiated.
+   * @dev DEPRECATED in favor of BridgingInitiatedV2.
+   * @param sender The indexed sender address.
+   * @param recipient The recipient address.
+   * @param token The indexed token address.
+   * @param amount The indexed token amount.
+   */
   event BridgingInitiated(address indexed sender, address recipient, address indexed token, uint256 indexed amount);
+
+  /**
+   * @notice Emitted when token bridging is initiated.
+   * @param sender The indexed sender address.
+   * @param recipient The indexed recipient address.
+   * @param token The indexed token address.
+   * @param amount The token amount.
+   */
   event BridgingInitiatedV2(address indexed sender, address indexed recipient, address indexed token, uint256 amount);
-  /// @dev DEPRECATED in favor of BridgingFinalizedV2.
+
+  /**
+   * @notice Emitted when token bridging is finalized.
+   * @dev DEPRECATED in favor of BridgingFinalizedV2.
+   * @param nativeToken The indexed native token address.
+   * @param bridgedToken The indexed bridged token address.
+   * @param amount The indexed token amount.
+   * @param recipient The recipient address.
+   */
   event BridgingFinalized(
     address indexed nativeToken,
     address indexed bridgedToken,
     uint256 indexed amount,
     address recipient
   );
+
+  /**
+   * @notice Emitted when token bridging is finalized.
+   * @param nativeToken The indexed native token address.
+   * @param bridgedToken The indexed bridged token address.
+   * @param amount The token amount.
+   * @param recipient The indexed recipient address.
+   */
   event BridgingFinalizedV2(
     address indexed nativeToken,
     address indexed bridgedToken,
     uint256 amount,
     address indexed recipient
   );
+
+  /**
+   * @notice Emitted when a new token is seen being bridged on the origin chain for the first time.
+   * @param token The indexed token address.
+   */
   event NewToken(address indexed token);
+
+  /**
+   * @notice Emitted when a new token is deployed.
+   * @param bridgedToken The indexed bridged token address.
+   * @param nativeToken The indexed native token address.
+   */
   event NewTokenDeployed(address indexed bridgedToken, address indexed nativeToken);
+
+  /**
+   * @notice Emitted when the remote token bridge is set.
+   * @param remoteTokenBridge The indexed remote token bridge address.
+   * @param setBy The indexed address that set the remote token bridge.
+   */
   event RemoteTokenBridgeSet(address indexed remoteTokenBridge, address indexed setBy);
+
+  /**
+   * @notice Emitted when the token is set as deployed.
+   * @dev This can be triggered by anyone calling confirmDeployment on the alternate chain.
+   * @param token The indexed token address.
+   */
   event TokenDeployed(address indexed token);
+
+  /**
+   * @notice Emitted when the token deployment is confirmed.
+   * @dev This can be triggered by anyone provided there is correctly mapped token data.
+   * @param tokens The token address list.
+   * @param confirmedBy The indexed address confirming deployment.
+   */
   event DeploymentConfirmed(address[] tokens, address indexed confirmedBy);
+
+  /**
+   * @notice Emitted when the message service address is set.
+   * @param newMessageService The indexed new message service address.
+   * @param oldMessageService The indexed old message service address.
+   * @param setBy The indexed address setting the new message service address.
+   */
   event MessageServiceUpdated(
     address indexed newMessageService,
     address indexed oldMessageService,
     address indexed setBy
   );
 
+  /**
+   * @dev Thrown when attempting to bridge a reserved token.
+   */
   error ReservedToken(address token);
+
+  /**
+   * @dev Thrown when the remote token bridge is already set.
+   */
   error RemoteTokenBridgeAlreadySet(address remoteTokenBridge);
+
+  /**
+   * @dev Thrown when attempting to reserve an already bridged token.
+   */
   error AlreadyBridgedToken(address token);
+
+  /**
+   * @dev Thrown when the permit data is invalid.
+   */
   error InvalidPermitData(bytes4 permitData, bytes4 permitSelector);
+
+  /**
+   * @dev Thrown when the permit is not from the sender.
+   */
   error PermitNotFromSender(address owner);
+
+  /**
+   * @dev Thrown when the permit does not grant spending to the bridge.
+   */
   error PermitNotAllowingBridge(address spender);
+
+  /**
+   * @dev Thrown when the amount being bridged is zero.
+   */
   error ZeroAmountNotAllowed(uint256 amount);
+
+  /**
+   * @dev Thrown when trying to unreserve a non-reserved token.
+   */
   error NotReserved(address token);
+
+  /**
+   * @dev Thrown when trying to confirm deployment of a non-deployed token.
+   */
   error TokenNotDeployed(address token);
+
+  /**
+   * @dev Thrown when trying to set a custom contract on a bridged token.
+   */
   error AlreadyBrigedToNativeTokenSet(address token);
+
+  /**
+   * @dev Thrown when trying to set a custom contract on an already set token.
+   */
   error NativeToBridgedTokenAlreadySet(address token);
+
+  /**
+   * @dev Thrown when trying to set a token that is already either native, deployed or reserved.
+   */
   error StatusAddressNotAllowed(address token);
+
+  /**
+   * @dev Thrown when the decimals for a token cannot be determined.
+   */
   error DecimalsAreUnknown(address token);
 
   /**