Merge pull request #122 from pods-finance/fix/l03-missing-docstrings

[OZ#2: L-03] Missing docstrings

contracts/configuration/ConfigurationManager.sol

@@ -17,11 +17,7 @@ contract ConfigurationManager is IConfigurationManager, Ownable {
     address private immutable _global = address(0);
 
     /**
-     * @notice Set specific parameters to a contract or globally across multiple contracts.
-     * @dev Use `address(0)` to set a global parameter.
-     * @param target The contract address
-     * @param name The parameter name
-     * @param value The parameter value
+     * @inheritdoc IConfigurationManager
      */
     function setParameter(
         address target,
@@ -33,26 +29,21 @@ contract ConfigurationManager is IConfigurationManager, Ownable {
     }
 
     /**
-     * @notice Retrieves the value of a parameter set to contract.
-     * @param target The contract address
-     * @param name The parameter name
+     * @inheritdoc IConfigurationManager
      */
     function getParameter(address target, bytes32 name) external view override returns (uint256) {
         return _parameters[target][name];
     }
 
     /**
-     * @notice Retrieves the value of a parameter shared between multiple contracts.
-     * @param name The parameter name
+     * @inheritdoc IConfigurationManager
      */
     function getGlobalParameter(bytes32 name) external view override returns (uint256) {
         return _parameters[_global][name];
     }
 
     /**
-     * @notice Defines a cap value to a contract.
-     * @param target The contract address
-     * @param value Cap amount
+     * @inheritdoc IConfigurationManager
      */
     function setCap(address target, uint256 value) external override onlyOwner {
         if (target == address(0)) revert ConfigurationManager__TargetCannotBeTheZeroAddress();
@@ -61,28 +52,22 @@ contract ConfigurationManager is IConfigurationManager, Ownable {
     }
 
     /**
-     * @notice Get the value of a defined cap.
-     * @dev Note that 0 cap means that the contract is not capped
-     * @param target The contract address
+     * @inheritdoc IConfigurationManager
      */
     function getCap(address target) external view override returns (uint256) {
         return _caps[target];
     }
 
     /**
-     * @notice Sets the allowance to migrate to a `vault` address.
-     * @param oldVault The current vault address
-     * @param newVault The vault where assets are going to be migrated to
+     * @inheritdoc IConfigurationManager
      */
     function setVaultMigration(address oldVault, address newVault) external override onlyOwner {
         _allowedVaults[oldVault] = newVault;
         emit VaultAllowanceSet(oldVault, newVault);
     }
 
     /**
-     * @notice Returns if the migration for a vault is allowed.
-     * @param oldVault The current vault address
-     * @param newVault The vault where assets are going to be migrated to
+     * @inheritdoc IConfigurationManager
      */
     function isVaultMigrationAllowed(address oldVault, address newVault) external view override returns (bool) {
         return _allowedVaults[oldVault] == newVault;

contracts/interfaces/IConfigurationManager.sol

@@ -2,28 +2,69 @@
 
 pragma solidity 0.8.17;
 
+/**
+ * @title IConfigurationManager
+ * @notice Allows contracts to read protocol-wide configuration modules
+ * @author Pods Finance
+ */
 interface IConfigurationManager {
     event SetCap(address indexed target, uint256 value);
     event ParameterSet(address indexed target, bytes32 indexed name, uint256 value);
     event VaultAllowanceSet(address indexed oldVault, address indexed newVault);
 
     error ConfigurationManager__TargetCannotBeTheZeroAddress();
 
+    /**
+     * @notice Set specific parameters to a contract or globally across multiple contracts.
+     * @dev Use `address(0)` to set a global parameter.
+     * @param target The contract address
+     * @param name The parameter name
+     * @param value The parameter value
+     */
     function setParameter(
         address target,
         bytes32 name,
         uint256 value
     ) external;
 
+    /**
+     * @notice Retrieves the value of a parameter set to contract.
+     * @param target The contract address
+     * @param name The parameter name
+     */
     function getParameter(address target, bytes32 name) external view returns (uint256);
 
+    /**
+     * @notice Retrieves the value of a parameter shared between multiple contracts.
+     * @param name The parameter name
+     */
     function getGlobalParameter(bytes32 name) external view returns (uint256);
 
+    /**
+     * @notice Defines a cap value to a contract.
+     * @param target The contract address
+     * @param value Cap amount
+     */
     function setCap(address target, uint256 value) external;
 
+    /**
+     * @notice Get the value of a defined cap.
+     * @dev Note that 0 cap means that the contract is not capped
+     * @param target The contract address
+     */
     function getCap(address target) external view returns (uint256);
 
+    /**
+     * @notice Sets the allowance to migrate to a `vault` address.
+     * @param oldVault The current vault address
+     * @param newVault The vault where assets are going to be migrated to
+     */
     function setVaultMigration(address oldVault, address newVault) external;
 
+    /**
+     * @notice Returns if the migration for a vault is allowed.
+     * @param oldVault The current vault address
+     * @param newVault The vault where assets are going to be migrated to
+     */
     function isVaultMigrationAllowed(address oldVault, address newVault) external view returns (bool);
 }

contracts/interfaces/ICurvePool.sol

@@ -2,14 +2,36 @@
 
 pragma solidity 0.8.17;
 
+/**
+ * @title ICurvePool Curve ETH/stETH StableSwap
+ * @notice Curve ETH/stETH StableSwap Interface
+ * @author Pods Finance
+ */
 interface ICurvePool {
+    /**
+     * @notice Perform an exchange between two coins
+     * @dev Index values can be found via the `coins` public getter method
+     * @param from Index value for the coin to send
+     * @param to Index value of the coin to receive
+     * @param input Amount of `from` being exchanged
+     * @param minOutput Minimum amount of `to` to receive
+     * @return output Actual amount of `to` received
+     */
     function exchange(
         int128 from,
         int128 to,
         uint256 input,
         uint256 minOutput
     ) external payable returns (uint256 output);
 
+    /**
+     * @notice Check price between two coins
+     * @dev Index values can be found via the `coins` public getter method
+     * @param from Index value for the coin to send
+     * @param to Index value of the coin to receive
+     * @param input Amount of `from` being exchanged
+     * @return output estimated `to` received
+     */
     function get_dy(
         int128 from,
         int128 to,

contracts/interfaces/IVault.sol

@@ -5,6 +5,11 @@ pragma solidity 0.8.17;
 import { IERC20Permit } from "@openzeppelin/contracts/token/ERC20/extensions/draft-IERC20Permit.sol";
 import { IERC4626 } from "@openzeppelin/contracts/interfaces/IERC4626.sol";
 
+/**
+ * @title IVault
+ * @notice Interface contract for Pods Vault
+ * @author Pods Finance
+ */
 interface IVault is IERC4626, IERC20Permit {
     error IVault__CallerIsNotTheController();
     error IVault__NotProcessingDeposits();

contracts/libs/CastUint.sol

@@ -2,6 +2,11 @@
 
 pragma solidity 0.8.17;
 
+/**
+ * @title CastUint
+ * @notice library to convert uint256 to address
+ * @author Pods Finance
+ */
 library CastUint {
     /**
      * @dev Strips and converts a `uint256` to `address`

contracts/mixins/Capped.sol

@@ -4,6 +4,11 @@ pragma solidity 0.8.17;
 
 import { IConfigurationManager } from "../interfaces/IConfigurationManager.sol";
 
+/**
+ * @title Capped
+ * @notice Mixin responsible for managing Vault's cap
+ * @author Pods Finance
+ */
 abstract contract Capped {
     IConfigurationManager private immutable _configuration;
     uint256 public spentCap;

contracts/proxy/ETHAdapter.sol

@@ -8,29 +8,37 @@ import { Address } from "@openzeppelin/contracts/utils/Address.sol";
 import { ICurvePool } from "../interfaces/ICurvePool.sol";
 import { IVault } from "../interfaces/IVault.sol";
 
+/**
+ * @title ETHAdapter
+ * @notice A Proxy contract responsible for converting ETH into stETH and depositing into the Vault
+ * @author Pods Finance
+ */
 contract ETHAdapter {
     using SafeERC20 for IERC20;
     using Address for address payable;
 
+    /**
+     * @notice Curve's pool ETH <> stETH
+     */
     ICurvePool public immutable pool;
 
     /**
-     * @dev ETH coin index in the Curve Pool
+     * @notice ETH coin index in the Curve Pool
      */
     int128 public constant ETH_INDEX = 0;
 
     /**
-     * @dev stETH coin index in the Curve Pool
+     * @notice stETH coin index in the Curve Pool
      */
     int128 public constant STETH_INDEX = 1;
 
     /**
-     * @dev ETH token address representation
+     * @notice ETH token address representation
      */
     address public constant ETH_ADDRESS = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;
 
     /**
-     * @dev stETH token address representation
+     * @notice stETH token address representation
      */
     address public constant STETH_ADDRESS = 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84;
 
@@ -45,14 +53,31 @@ contract ETHAdapter {
         pool = _pool;
     }
 
+    /**
+     * @notice Convert `ethAmount` ETH to stETH using Curve pool
+     * @param ethAmount Amount of ETH to convert
+     * @return uint256 Amount of stETH received in exchange
+     */
     function convertToSTETH(uint256 ethAmount) external view returns (uint256) {
         return pool.get_dy(ETH_INDEX, STETH_INDEX, ethAmount);
     }
 
+    /**
+     * @notice Convert 'stETHAmount' stETH to ETH using Curve pool
+     * @param stETHAmount Amount of stETH to convert
+     * @return uint256 Amount of ETH received in exchange
+     */
     function convertToETH(uint256 stETHAmount) external view returns (uint256) {
         return pool.get_dy(STETH_INDEX, ETH_INDEX, stETHAmount);
     }
 
+    /**
+     * @notice Deposit `msg.value` of ETH, convert to stETH and deposit into `vault`
+     * @param vault Pods' strategy vault that will receive the stETH
+     * @param receiver Address that will be the owner of the Vault's shares
+     * @param minOutput slippage control. Minimum acceptable amount of stETH
+     * @return uint256 Amount of shares returned by vault ERC4626 contract
+     */
     function deposit(
         IVault vault,
         address receiver,
@@ -64,6 +89,14 @@ contract ETHAdapter {
         return vault.deposit(assets, receiver);
     }
 
+    /**
+     * @notice Redeem `shares` shares, receive stETH, trade stETH for ETH and send to receiver
+     * @param vault Pods' strategy vault that will receive the shares and payback stETH
+     * @param shares Amount of Vault's shares to redeem
+     * @param receiver Address that will receive back the ETH withdrawn from the `vault`
+     * @param minOutput slippage control. Minimum acceptable amount of ETH
+     * @return uint256 Amount of assets received from Vault ERC4626
+     */
     function redeem(
         IVault vault,
         uint256 shares,
@@ -75,6 +108,19 @@ contract ETHAdapter {
         return assets;
     }
 
+    /**
+     * @notice redeemWithPermit `shares` shares, receive stETH, trade stETH for ETH and send to receiver
+     * @dev Do not need to approve the shares in advance. The vault tokenized shares supports Permit
+     * @param vault Pods' strategy vault that will receive the shares and payback stETH
+     * @param shares Amount of Vault's shares to redeem
+     * @param receiver Address that will receive back the ETH withdrawn from `vault`
+     * @param minOutput slippage control. Minimum acceptable amount of ETH
+     * @param deadline deadline that this transaction will be valid
+     * @param v recovery id
+     * @param r ECDSA signature output
+     * @param s ECDSA signature output
+     * @return assets Amount of assets received from Vault ERC4626
+     */
     function redeemWithPermit(
         IVault vault,
         uint256 shares,
@@ -90,6 +136,15 @@ contract ETHAdapter {
         _returnETH(vault, receiver, minOutput);
     }
 
+    /**
+     * @notice Withdraw `assets` assets, receive stETH, trade stETH for ETH and send to receiver
+     * @dev Do not need to approve the shares in advance. The vault tokenized shares supports Permit
+     * @param vault Pods' strategy vault that will receive the shares and payback stETH
+     * @param assets Amount of assets (stETH) to redeem
+     * @param receiver Address that will receive back the ETH withdrawn from the Vault
+     * @param minOutput slippage control. Minimum acceptable amount of ETH
+     * @return shares Amount of shares burned in order to receive assets
+     */
     function withdraw(
         IVault vault,
         uint256 assets,
@@ -100,6 +155,19 @@ contract ETHAdapter {
         _returnETH(vault, receiver, minOutput);
     }
 
+    /**
+     * @notice withdrawWithPermit `assets` assets, receive stETH, trade stETH for ETH and send to receiver
+     * @dev Do not need to approve the shares in advance. Vault's tokenized shares supports Permit
+     * @param vault Pods' strategy vault that will receive the shares and payback stETH
+     * @param assets Amount of assets (stETH) to redeem
+     * @param receiver Address that will receive back the ETH withdrawn from the Vault
+     * @param minOutput slippage control. Minimum acceptable amount of ETH
+     * @param deadline deadline that this transaction will be valid
+     * @param v recovery id
+     * @param r ECDSA signature output
+     * @param s ECDSA signature output
+     * @return shares Amount of shares burned in order to receive assets
+     */
     function withdrawWithPermit(
         IVault vault,
         uint256 assets,
@@ -121,6 +189,10 @@ contract ETHAdapter {
     */
     receive() external payable {}
 
+    /**
+     *  @dev internal function used to convert stETH into ETH and send back
+     * to receiver
+     */
     function _returnETH(
         IVault vault,
         address receiver,