docs(contracts): OZ-N07 Missing or Inconsistent Documentation (scroll…

…-tech#1098) Co-authored-by: Péter Garamvölgyi <[email protected]>
exo9planet · Feb 5, 2024 · 3671793 · 3671793
1 parent 999db62
commit 3671793
Show file tree

Hide file tree

Showing 11 changed files with 43 additions and 44 deletions.
diff --git a/contracts/src/L1/gateways/L1CustomERC20Gateway.sol b/contracts/src/L1/gateways/L1CustomERC20Gateway.sol
@@ -44,8 +44,8 @@ contract L1CustomERC20Gateway is L1ERC20Gateway {
     /// @notice Constructor for `L1CustomERC20Gateway` implementation contract.
     ///
     /// @param _counterpart The address of `L2USDCGateway` contract in L2.
-    /// @param _router The address of `L1GatewayRouter` contract.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _router The address of `L1GatewayRouter` contract in L1.
+    /// @param _messenger The address of `L1ScrollMessenger` contract L1.
     constructor(
         address _counterpart,
         address _router,
@@ -60,8 +60,8 @@ contract L1CustomERC20Gateway is L1ERC20Gateway {
     /// @dev The parameters `_counterpart`, `_router` and `_messenger` are no longer used.
     ///
     /// @param _counterpart The address of L2CustomERC20Gateway in L2.
-    /// @param _router The address of L1GatewayRouter.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _router The address of L1GatewayRouter in L1.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(
         address _counterpart,
         address _router,

diff --git a/contracts/src/L1/gateways/L1ERC1155Gateway.sol b/contracts/src/L1/gateways/L1ERC1155Gateway.sol
@@ -44,14 +44,14 @@ contract L1ERC1155Gateway is ERC1155HolderUpgradeable, ScrollGatewayBase, IL1ERC
     /// @notice Constructor for `L1ERC1155Gateway` implementation contract.
     ///
     /// @param _counterpart The address of `L1ERC1155Gateway` contract in L2.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     constructor(address _counterpart, address _messenger) ScrollGatewayBase(_counterpart, address(0), _messenger) {
         _disableInitializers();
     }
 
     /// @notice Initialize the storage of L1ERC1155Gateway.
     /// @param _counterpart The address of L2ERC1155Gateway in L2.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(address _counterpart, address _messenger) external initializer {
         ERC1155HolderUpgradeable.__ERC1155Holder_init();
         ERC1155ReceiverUpgradeable.__ERC1155Receiver_init();

diff --git a/contracts/src/L1/gateways/L1ERC721Gateway.sol b/contracts/src/L1/gateways/L1ERC721Gateway.sol
@@ -44,7 +44,7 @@ contract L1ERC721Gateway is ERC721HolderUpgradeable, ScrollGatewayBase, IL1ERC72
     /// @notice Constructor for `L2ERC721Gateway` implementation contract.
     ///
     /// @param _counterpart The address of `L2ERC721Gateway` contract in L2.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     constructor(address _counterpart, address _messenger) ScrollGatewayBase(_counterpart, address(0), _messenger) {
         _disableInitializers();
     }
@@ -54,7 +54,7 @@ contract L1ERC721Gateway is ERC721HolderUpgradeable, ScrollGatewayBase, IL1ERC72
     /// @dev The parameters `_counterpart` and `_messenger` are no longer used.
     ///
     /// @param _counterpart The address of L2ERC721Gateway in L2.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(address _counterpart, address _messenger) external initializer {
         ERC721HolderUpgradeable.__ERC721Holder_init();
 

diff --git a/contracts/src/L1/gateways/L1ETHGateway.sol b/contracts/src/L1/gateways/L1ETHGateway.sol
@@ -24,8 +24,8 @@ contract L1ETHGateway is ScrollGatewayBase, IL1ETHGateway, IMessageDropCallback
     /// @notice Constructor for `L1ETHGateway` implementation contract.
     ///
     /// @param _counterpart The address of `L2ETHGateway` contract in L2.
-    /// @param _router The address of `L1GatewayRouter` contract.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _router The address of `L1GatewayRouter` contract in L1.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     constructor(
         address _counterpart,
         address _router,
@@ -41,8 +41,8 @@ contract L1ETHGateway is ScrollGatewayBase, IL1ETHGateway, IMessageDropCallback
     /// @dev The parameters `_counterpart`, `_router` and `_messenger` are no longer used.
     ///
     /// @param _counterpart The address of L2ETHGateway in L2.
-    /// @param _router The address of L1GatewayRouter.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _router The address of L1GatewayRouter in L1.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(
         address _counterpart,
         address _router,

diff --git a/contracts/src/L1/gateways/L1StandardERC20Gateway.sol b/contracts/src/L1/gateways/L1StandardERC20Gateway.sol
@@ -52,8 +52,8 @@ contract L1StandardERC20Gateway is L1ERC20Gateway {
     /// @notice Constructor for `L1StandardERC20Gateway` implementation contract.
     ///
     /// @param _counterpart The address of `L2StandardERC20Gateway` contract in L2.
-    /// @param _router The address of `L1GatewayRouter` contract.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _router The address of `L1GatewayRouter` contract in L1.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     /// @param _l2TokenImplementation The address of `ScrollStandardERC20` implementation in L2.
     /// @param _l2TokenFactory The address of `ScrollStandardERC20Factory` contract in L2.
     constructor(
@@ -79,8 +79,8 @@ contract L1StandardERC20Gateway is L1ERC20Gateway {
     /// `_l2TokenFactory` are no longer used.
     ///
     /// @param _counterpart The address of L2StandardERC20Gateway in L2.
-    /// @param _router The address of L1GatewayRouter.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _router The address of L1GatewayRouter in L1.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(
         address _counterpart,
         address _router,
@@ -89,11 +89,6 @@ contract L1StandardERC20Gateway is L1ERC20Gateway {
         address /*_l2TokenFactory*/
     ) external initializer {
         ScrollGatewayBase._initialize(_counterpart, _router, _messenger);
-
-        /* comments out since not used any more
-        __l2TokenImplementation = _l2TokenImplementation;
-        __l2TokenFactory = _l2TokenFactory;
-        */
     }
 
     /*************************

diff --git a/contracts/src/L1/gateways/L1WETHGateway.sol b/contracts/src/L1/gateways/L1WETHGateway.sol
@@ -38,8 +38,8 @@ contract L1WETHGateway is L1ERC20Gateway {
     /// @param _WETH The address of WETH in L1.
     /// @param _l2WETH The address of WETH in L2.
     /// @param _counterpart The address of `L2WETHGateway` contract in L2.
-    /// @param _router The address of `L1GatewayRouter` contract.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _router The address of `L1GatewayRouter` contract in L1.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     constructor(
         address _WETH,
         address _l2WETH,
@@ -58,9 +58,12 @@ contract L1WETHGateway is L1ERC20Gateway {
     }
 
     /// @notice Initialize the storage of L1WETHGateway.
+    ///
+    /// @dev The parameters `_counterpart`, `_router` and `_messenger` are no longer used.
+    ///
     /// @param _counterpart The address of L2ETHGateway in L2.
-    /// @param _router The address of L1GatewayRouter.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _router The address of L1GatewayRouter in L1.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(
         address _counterpart,
         address _router,

diff --git a/contracts/src/L1/gateways/usdc/L1USDCGateway.sol b/contracts/src/L1/gateways/usdc/L1USDCGateway.sol
@@ -54,8 +54,8 @@ contract L1USDCGateway is L1ERC20Gateway, IUSDCBurnableSourceBridge {
     /// @param _l1USDC The address of USDC in L1.
     /// @param _l2USDC The address of USDC in L2.
     /// @param _counterpart The address of `L2USDCGateway` contract in L2.
-    /// @param _router The address of `L1GatewayRouter` contract.
-    /// @param _messenger The address of `L1ScrollMessenger` contract.
+    /// @param _router The address of `L1GatewayRouter` contract in L1.
+    /// @param _messenger The address of `L1ScrollMessenger` contract in L1.
     constructor(
         address _l1USDC,
         address _l2USDC,
@@ -78,8 +78,8 @@ contract L1USDCGateway is L1ERC20Gateway, IUSDCBurnableSourceBridge {
     /// @dev The parameters `_counterpart`, `_router` and `_messenger` are no longer used.
     ///
     /// @param _counterpart The address of L2USDCGateway in L2.
-    /// @param _router The address of L1GatewayRouter.
-    /// @param _messenger The address of L1ScrollMessenger.
+    /// @param _router The address of L1GatewayRouter in L1.
+    /// @param _messenger The address of L1ScrollMessenger in L1.
     function initialize(
         address _counterpart,
         address _router,

diff --git a/contracts/src/L1/rollup/IL2GasPriceOracle.sol b/contracts/src/L1/rollup/IL2GasPriceOracle.sol
@@ -3,9 +3,10 @@
 pragma solidity ^0.8.16;
 
 interface IL2GasPriceOracle {
-    /// @notice The latest known l2 base fee.
+    /// @notice Return the latest known l2 base fee.
     function l2BaseFee() external view returns (uint256);
 
+    /// @notice Return the address of whitelist contract.
     function whitelist() external view returns (address);
 
     /// @notice Estimate fee for cross chain message call.

diff --git a/contracts/src/L2/gateways/L2ETHGateway.sol b/contracts/src/L2/gateways/L2ETHGateway.sol
@@ -38,8 +38,8 @@ contract L2ETHGateway is ScrollGatewayBase, IL2ETHGateway {
     /// @dev The parameters `_counterpart`, `_router` and `_messenger` are no longer used.
     ///
     /// @param _counterpart The address of L1ETHGateway in L1.
-    /// @param _router The address of L2GatewayRouter.
-    /// @param _messenger The address of L2ScrollMessenger.
+    /// @param _router The address of L2GatewayRouter in L2.
+    /// @param _messenger The address of L2ScrollMessenger in L2.
     function initialize(
         address _counterpart,
         address _router,
@@ -98,6 +98,11 @@ contract L2ETHGateway is ScrollGatewayBase, IL2ETHGateway {
      * Internal Functions *
      **********************/
 
+    /// @dev The internal ETH withdraw implementation.
+    /// @param _to The address of recipient's account on L1.
+    /// @param _amount The amount of ETH to be withdrawn.
+    /// @param _data Optional data to forward to recipient's account.
+    /// @param _gasLimit Optional gas limit to complete the deposit on L1.
     function _withdraw(
         address _to,
         uint256 _amount,

diff --git a/contracts/src/L2/gateways/L2GatewayRouter.sol b/contracts/src/L2/gateways/L2GatewayRouter.sol
@@ -54,8 +54,7 @@ contract L2GatewayRouter is OwnableUpgradeable, IL2GatewayRouter {
     ///
     /// @param _defaultERC20Gateway The address of default ERC20 Gateway contract.
     function initialize(
-        address,
-        /*_ethGateway*/
+        address, /*_ethGateway*/
         address _defaultERC20Gateway
     ) external initializer {
         OwnableUpgradeable.__Ownable_init();

diff --git a/contracts/src/L2/gateways/L2StandardERC20Gateway.sol b/contracts/src/L2/gateways/L2StandardERC20Gateway.sol
@@ -45,9 +45,9 @@ contract L2StandardERC20Gateway is L2ERC20Gateway {
     /// @notice Constructor for `L2StandardERC20Gateway` implementation contract.
     ///
     /// @param _counterpart The address of `L1StandardERC20Gateway` contract in L1.
-    /// @param _router The address of `L2GatewayRouter` contract.
-    /// @param _messenger The address of `L2ScrollMessenger` contract.
-    /// @param _tokenFactory The address of ScrollStandardERC20Factory.
+    /// @param _router The address of `L2GatewayRouter` contract in L2.
+    /// @param _messenger The address of `L2ScrollMessenger` contract in L2.
+    /// @param _tokenFactory The address of `ScrollStandardERC20Factory` contract in L2.
     constructor(
         address _counterpart,
         address _router,
@@ -65,20 +65,16 @@ contract L2StandardERC20Gateway is L2ERC20Gateway {
     ///
     /// @dev The parameters `_counterpart`, `_router`, `_messenger` and `_tokenFactory` are no longer used.
     ///
-    /// @param _counterpart The address of L1ETHGateway in L1.
-    /// @param _router The address of L2GatewayRouter.
-    /// @param _messenger The address of L2ScrollMessenger.
+    /// @param _counterpart The address of `L1StandardERC20Gateway` contract in L1.
+    /// @param _router The address of `L2GatewayRouter` contract in L2.
+    /// @param _messenger The address of `L2ScrollMessenger` contract in L2.
     function initialize(
         address _counterpart,
         address _router,
         address _messenger,
         address /*_tokenFactory*/
     ) external initializer {
         ScrollGatewayBase._initialize(_counterpart, _router, _messenger);
-
-        /* comment out since no longer used
-        __tokenFactory = _tokenFactory;
-        */
     }
 
     /*************************