add documentation comments

contracts/DODOV3MM/D3Pool/D3Funding.sol

@@ -13,6 +13,8 @@
     using SafeERC20 for IERC20;
 
     /// @notice borrow tokens from vault
+    /// @param token The address of the token to borrow
+    /// @param amount The amount of tokens to borrow
     function borrow(address token, uint256 amount) external onlyOwner nonReentrant poolOngoing {
         // call vault's poolBorrow function
         ID3Vault(state._D3_VAULT_).poolBorrow(token, amount);
@@ -23,29 +25,33 @@
         }
 
         _updateReserve(token);
         require(checkSafe(), Errors.NOT_SAFE);
         require(checkBorrowSafe(), Errors.NOT_BORROW_SAFE);
     }
 
     /// @notice repay vault with certain amount of borrowed assets 
+    /// @param token The address of the token to repay
+    /// @param amount The amount of tokens to repay
     function repay(address token, uint256 amount) external onlyOwner nonReentrant poolOngoing {
         // call vault's poolRepay
         ID3Vault(state._D3_VAULT_).poolRepay(token, amount);
 
         _updateReserve(token);
         require(checkSafe(), Errors.NOT_SAFE);
     }
 
     /// @notice repay vault all debt of this token
+    /// @param token The address of the token to repay all debt
     function repayAll(address token) external onlyOwner nonReentrant poolOngoing {
         ID3Vault(state._D3_VAULT_).poolRepayAll(token);
 
         _updateReserve(token);
         require(checkSafe(), Errors.NOT_SAFE);
 
     }
 
     /// @notice used through liquidation
+    /// @param token The address of the token to update reserve
     function updateReserveByVault(address token) external onlyVault {
         uint256 allowance = IERC20(token).allowance(address(this), state._D3_VAULT_);
         if(allowance < type(uint256).max) {
@@ -55,8 +61,9 @@
     }
 
     /// @notice maker deposit, anyone could deposit but only maker could withdraw
+    /// @param token The address of the token to deposit
     function makerDeposit(address token) external nonReentrant poolOngoing {
         require(ID3Oracle(state._ORACLE_).isFeasible(token), Errors.TOKEN_NOT_FEASIBLE);
         if (!state.hasDepositedToken[token]) {
             state.hasDepositedToken[token] = true;
             state.depositedTokenList.push(token);
@@ -69,48 +76,59 @@
         if(_checkTokenInTokenlist(token) && allowance < type(uint256).max) {
             IERC20(token).forceApprove(state._D3_VAULT_, type(uint256).max);
         }
         require(checkSafe(), Errors.NOT_SAFE);
 
         emit MakerDeposit(token, tokenInAmount);
     }
 
+    /// @notice maker withdraw, only maker could withdraw
+    /// @param to The address to receive the withdrawn tokens
+    /// @param token The address of the token to withdraw
+    /// @param amount The amount of tokens to withdraw
     function makerWithdraw(address to, address token, uint256 amount) external onlyOwner nonReentrant poolOngoing {
         IERC20(token).safeTransfer(to, amount);
 
         _updateReserve(token);
         require(checkSafe(), Errors.NOT_SAFE);
         require(checkBorrowSafe(), Errors.NOT_BORROW_SAFE);
 
         emit MakerWithdraw(to, token, amount);
     }
 
-    // below IM: not safe!
+    /// @notice check if the pool is safe
     function checkSafe() public view returns (bool) {
         return ID3Vault(state._D3_VAULT_).checkSafe(address(this));
     }
 
-    // check when borrowing asset
+    /// @notice check if the pool is safe when borrowing asset
     function checkBorrowSafe() public view returns (bool) {
         return ID3Vault(state._D3_VAULT_).checkBorrowSafe(address(this));
     }
 
-    // blow MM: dangerous!
+    /// @notice check if the pool can be liquidated
     function checkCanBeLiquidated() public view returns (bool) {
         return ID3Vault(state._D3_VAULT_).checkCanBeLiquidated(address(this));
     }
 
+    /// @notice start the liquidation process
     function startLiquidation() external onlyVault {
         isInLiquidation = true;
     }
 
+    /// @notice finish the liquidation process
     function finishLiquidation() external onlyVault {
         isInLiquidation = false;
     }
 
+    /// @notice update the reserve of a token
+    /// @param token The address of the token to update reserve
     function _updateReserve(address token) internal {
         state.balances[token] = IERC20(token).balanceOf(address(this));
     }
 
+    /// @notice check if a token is in the token list
+    /// @param token The address of the token to check
+    /// @return true if the token is in the token list, false otherwise
     function _checkTokenInTokenlist(address token) internal view returns(bool){
         return ID3Vault(state._D3_VAULT_).tokens(token); 
     }

contracts/DODOV3MM/D3Pool/D3MM.sol

@@ -5,8 +5,16 @@ import {D3Trading} from "./D3Trading.sol";
 import {IFeeRateModel} from "../../intf/IFeeRateModel.sol";
 import {ID3Maker} from "../intf/ID3Maker.sol";
 
+/// @title D3MM - DODO V3 Market Making Pool
+/// @notice This contract inherits from D3Trading, providing more view functions.
 contract D3MM is D3Trading {
-    /// @notice init D3MM pool
+    /// @notice Initializes the D3MM pool with the provided parameters
+    /// @param creator The address of the pool creator
+    /// @param maker The address of the D3Maker contract
+    /// @param vault The address of the vault contract
+    /// @param oracle The address of the oracle contract
+    /// @param feeRateModel The address of the fee rate model contract
+    /// @param maintainer The address of the maintainer contract
     function init(
         address creator,
         address maker,
@@ -24,30 +32,35 @@ contract D3MM is D3Trading {
         state._MAINTAINER_ = maintainer;
     }
 
-    // ============= Set ====================
+    /// @notice Sets a new D3Maker contract for the pool
+    /// @param newMaker The address of the new D3Maker contract
     function setNewMaker(address newMaker) external onlyOwner {
         state._MAKER_ = newMaker;
         allFlag = 0;
     }
 
-    // ============= View =================
+    /// @notice Returns the address of the pool creator
     function _CREATOR_() external view returns(address) {
         return state._CREATOR_;
     }
 
+    /// @notice Returns the fee rate for a given token
+    /// @param token The address of the token
     function getFeeRate(address token) external view returns(uint256 feeRate) {
         return IFeeRateModel(state._FEE_RATE_MODEL_).getFeeRate(token);
     }
 
+    /// @notice Returns the list of tokens in the pool
     function getPoolTokenlist() external view returns(address[] memory) {
         return ID3Maker(state._MAKER_).getPoolTokenListFromMaker();
     }
 
+    /// @notice Returns the list of tokens deposited in the pool
     function getDepositedTokenList() external view returns (address[] memory) {
         return state.depositedTokenList;
     }
 
-    /// @notice get basic pool info
+    /// @notice Returns the basic information of the pool
     function getD3MMInfo() external view returns (address vault, address oracle, address maker, address feeRateModel, address maintainer) {
         vault = state._D3_VAULT_;
         oracle = state._ORACLE_;
@@ -56,12 +69,13 @@ contract D3MM is D3Trading {
         maintainer = state._MAINTAINER_;
     }
 
-    /// @notice get a token's reserve in pool
+    /// @notice Returns the reserve of a given token in the pool
+    /// @param token The address of the token
     function getTokenReserve(address token) external view returns (uint256) {
         return state.balances[token];
     }
 
-    /// @notice get D3MM contract version
+    /// @notice Returns the version of the D3MM contract
     function version() external pure virtual returns (string memory) {
         return "D3MM 1.0.0";
     }

contracts/DODOV3MM/D3Pool/D3Maker.sol

@@ -26,13 +26,21 @@
     event SetNewToken(address indexed token);
 
     // ============== init =============
+    /// @notice Initializes the contract with the owner, pool, and maxInterval
+    /// @param owner The address of the owner
+    /// @param pool The address of the pool
+    /// @param maxInterval The maximum interval
     function init(address owner, address pool, uint256 maxInterval) external {
         initOwner(owner);
         _POOL_ = pool;
         state.heartBeat.maxInterval = maxInterval;
     }
 
     // ============= Read for tokenMMInfo =================
+    /// @notice Returns the TokenMMInfo for a given token
+    /// @param token The address of the token
+    /// @return tokenMMInfo The TokenMMInfo of the token
+    /// @return tokenIndex The index of the token
     function getTokenMMInfoForPool(address token)
         external
         view
@@ -65,9 +73,11 @@
 
     // ================== Read parameters ==============
 
-    /// @notice give one token's address, give back token's priceInfo
+    /// @notice This function returns the price set for a given token
+    /// @param token The address of the token
+    /// @return priceSet The price set of the token
     function getOneTokenPriceSet(address token) public view returns (uint80 priceSet) {
         require(state.priceListInfo.tokenIndexMap[token] > 0, Errors.INVALID_TOKEN);
         uint256 tokenOriIndex = state.priceListInfo.tokenIndexMap[token] - 1;
         uint256 tokenIndex = (tokenOriIndex / 2);
         uint256 tokenIndexInnerSlot = tokenIndex % MakerTypes.PRICE_QUANTITY_IN_ONE_SLOT;
@@ -80,6 +90,7 @@
     }
 
     /// @notice get one token index. odd for none-stable, even for stable,  true index = (tokenIndex[address] - 1) / 2
+    /// @param token The address of the token
     function getOneTokenOriginIndex(address token) public view returns (int256) {
         //require(state.priceListInfo.tokenIndexMap[token] > 0, Errors.INVALID_TOKEN);
         return int256(state.priceListInfo.tokenIndexMap[token]) - 1;
@@ -88,6 +99,7 @@
     /// @notice get all stable token Info
     /// @return numberOfStable stable tokens' quantity
     /// @return tokenPriceStable stable tokens' price slot array. each data contains up to 3 token prices
+    /// @return curFlag current flags for all token in one slot
     function getStableTokenInfo()
         external
         view
@@ -101,6 +113,7 @@
     /// @notice get all non-stable token Info
     /// @return number stable tokens' quantity
     /// @return tokenPrices stable tokens' price slot array. each data contains up to 3 token prices
+    /// @return curFlag current flags for all token in one slot
     function getNSTokenInfo() external view returns (uint256 number, uint256[] memory tokenPrices, uint256 curFlag) {
         number = state.priceListInfo.numberOfNS;
         tokenPrices = state.priceListInfo.tokenPriceNS;
@@ -122,6 +135,7 @@
             + (priceSet << (slotInnerIndex * MakerTypes.ONE_PRICE_BIT)) + rightPriceSet;
     }
 
+    /// @notice check heartbeat
     function checkHeartbeat() public view returns (bool) {
         if (block.timestamp - state.heartBeat.lastHeartBeat <= state.heartBeat.maxInterval) {
             return true;
@@ -130,13 +144,15 @@
         }
     }
 
+    /// @notice get pool's token list
     function getPoolTokenListFromMaker() external view returns(address[] memory tokenlist) {
         return poolTokenlist;
     }
 
     // ============= Set params ===========
 
     /// @notice maker could use multicall to set different params in one tx.
+    /// @param data A list of calldata to call
     function multicall(bytes[] calldata data) external returns (bytes[] memory results) {
         results = new bytes[](data.length);
         for (uint256 i = 0; i < data.length; i++) {
@@ -167,7 +183,7 @@
         uint16 kAsk,
         uint16 kBid
     ) external onlyOwner {
         require(state.priceListInfo.tokenIndexMap[token] == 0, Errors.HAVE_SET_TOKEN_INFO);
         // check amount
         require(kAsk >= 0 && kAsk <= 10000, Errors.K_LIMIT);
         require(kBid >= 0 && kBid <= 10000, Errors.K_LIMIT);
@@ -387,6 +403,7 @@
     }
 
     /// @notice set acceptable setting interval, if setting gap > maxInterval, swap will revert.
+    /// @param newMaxInterval The new max interval for heartbeat
     function setHeartbeat(uint256 newMaxInterval) public onlyOwner {
         state.heartBeat.maxInterval = newMaxInterval;