Merge pull request #157 from aave/refactor/add-cleanups-docs

Refactor/add cleanups docs

contracts/interfaces/IPool.sol

@@ -13,9 +13,9 @@ interface IPool {
   /**
    * @notice Emitted on mintUnbacked()
    * @param reserve The address of the underlying asset of the reserve
-   * @param user The address initiating the deposit
-   * @param onBehalfOf The beneficiary of the deposit, receiving the aTokens
-   * @param amount The amount deposited
+   * @param user The address initiating the supply
+   * @param onBehalfOf The beneficiary of the supplied assets, receiving the aTokens
+   * @param amount The amount of supplied assets
    * @param referral The referral code used
    **/
   event MintUnbacked(

contracts/interfaces/IReserveInterestRateStrategy.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: agpl-3.0
 pragma solidity 0.8.7;
 
-import {DataTypes} from './../protocol/libraries/types/DataTypes.sol';
+import {DataTypes} from '../protocol/libraries/types/DataTypes.sol';
 
 /**
  * @title IReserveInterestRateStrategy

contracts/misc/AaveProtocolDataProvider.sol

@@ -328,11 +328,11 @@ contract AaveProtocolDataProvider is IPoolDataProvider {
   }
 
   /**
-   * @notice Returns the address of the IR strategy
+   * @notice Returns the address of the Interest Rate strategy
    * @param asset The address of the underlying asset of the reserve
-   * @return irStrategyAddress The address of the IR strategy
+   * @return irStrategyAddress The address of the Interest Rate strategy
    */
-  function getIRStrategyAddress(address asset) external view returns (address irStrategyAddress) {
+  function getInterestRateStrategyAddress(address asset) external view returns (address irStrategyAddress) {
     DataTypes.ReserveData memory reserve = IPool(ADDRESSES_PROVIDER.getPool()).getReserveData(
       asset
     );

contracts/protocol/configuration/PoolAddressesProviderRegistry.sol

@@ -2,8 +2,8 @@
 pragma solidity 0.8.7;
 
 import {Ownable} from '../../dependencies/openzeppelin/contracts/Ownable.sol';
-import {IPoolAddressesProviderRegistry} from '../../interfaces/IPoolAddressesProviderRegistry.sol';
 import {Errors} from '../libraries/helpers/Errors.sol';
+import {IPoolAddressesProviderRegistry} from '../../interfaces/IPoolAddressesProviderRegistry.sol';
 
 /**
  * @title PoolAddressesProviderRegistry

contracts/protocol/libraries/aave-upgradeability/BaseImmutableAdminUpgradeabilityProxy.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: agpl-3.0
 pragma solidity 0.8.7;
 
-import '../../../dependencies/openzeppelin/upgradeability/BaseUpgradeabilityProxy.sol';
+import {BaseUpgradeabilityProxy} from '../../../dependencies/openzeppelin/upgradeability/BaseUpgradeabilityProxy.sol';
 
 /**
  * @title BaseImmutableAdminUpgradeabilityProxy

contracts/protocol/libraries/aave-upgradeability/InitializableImmutableAdminUpgradeabilityProxy.sol

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: agpl-3.0
 pragma solidity 0.8.7;
 
-import './BaseImmutableAdminUpgradeabilityProxy.sol';
-import '../../../dependencies/openzeppelin/upgradeability/InitializableUpgradeabilityProxy.sol';
+import {InitializableUpgradeabilityProxy} from '../../../dependencies/openzeppelin/upgradeability/InitializableUpgradeabilityProxy.sol';
+import {Proxy} from '../../../dependencies/openzeppelin/upgradeability/Proxy.sol';
+import {BaseImmutableAdminUpgradeabilityProxy} from './BaseImmutableAdminUpgradeabilityProxy.sol';
 
 /**
  * @title InitializableAdminUpgradeabilityProxy

contracts/protocol/libraries/configuration/UserConfiguration.sol

@@ -152,6 +152,15 @@ library UserConfiguration {
     return self.data == 0;
   }
 
+  /**
+   * @notice Returns the Isolation Mode state of the user
+   * @param self The configuration object
+   * @param reservesData The data of all the reserves
+   * @param reservesList The reserve list
+   * @return True if the user is in isolation mode, false otherwise
+   * @return The address of the first asset used as collateral
+   * @return The debt ceiling of the reserve
+   */
   function getIsolationModeState(
     DataTypes.UserConfigurationMap memory self,
     mapping(address => DataTypes.ReserveData) storage reservesData,
@@ -180,6 +189,11 @@ library UserConfiguration {
     return (false, address(0), 0);
   }
 
+  /**
+   * @notice Returns the address of the first asset used as collateral by the user
+   * @param self The configuration object
+   * @return The address of the first collateral asset
+   */
   function _getFirstAssetAsCollateralId(DataTypes.UserConfigurationMap memory self)
     internal
     pure

contracts/protocol/libraries/logic/BridgeLogic.sol

@@ -70,13 +70,13 @@ library BridgeLogic {
 
     reserve.updateInterestRates(reserveCache, asset, 0, 0);
 
-    bool isFirstDeposit = IAToken(reserveCache.aTokenAddress).mint(
+    bool isFirstSupply = IAToken(reserveCache.aTokenAddress).mint(
       onBehalfOf,
       amount,
       reserveCache.nextLiquidityIndex
     );
 
-    if (isFirstDeposit) {
+    if (isFirstSupply) {
       userConfig.setUsingAsCollateral(reserve.id, true);
       emit ReserveUsedAsCollateralEnabled(asset, onBehalfOf);
     }

contracts/protocol/libraries/logic/ValidationLogic.sol

@@ -41,7 +41,7 @@ library ValidationLogic {
   uint256 public constant HEALTH_FACTOR_LIQUIDATION_THRESHOLD = 1e18;
 
   // for borrowings in isolation mode, we give for granted that the eMode category for stablecoins is the category with id 1.
-  // this MUST be kept into account when configuring the stablecoins eMode category, otherwise users depositing asset in isolation
+  // this MUST be kept into account when configuring the stablecoins eMode category, otherwise users suplying asset in isolation
   // mode will NOT be able to borrow.
   uint256 public constant DEFAULT_ISOLATION_MODE_BORROW_CATEGORY = 1;
 
@@ -472,7 +472,7 @@ library ValidationLogic {
    * @notice Validates a flashloan action
    * @param reserveCache The cached data of the reserve
    */
-  function validateFlashloanSimple(DataTypes.ReserveCache memory reserveCache) internal view {
+  function validateFlashloanSimple(DataTypes.ReserveCache memory reserveCache) internal pure {
     require(!reserveCache.reserveConfiguration.getPaused(), Errors.VL_RESERVE_PAUSED);
     require(reserveCache.reserveConfiguration.getActive(), Errors.VL_NO_ACTIVE_RESERVE);
   }
@@ -662,7 +662,7 @@ library ValidationLogic {
       Errors.VL_INCONSISTENT_EMODE_CATEGORY
     );
 
-    //eMode can always be enabled if the user hasn't deposited anything
+    //eMode can always be enabled if the user hasn't supplied anything
     if (userConfig.isEmpty()) {
       return;
     }

contracts/protocol/libraries/types/DataTypes.sol

@@ -51,6 +51,8 @@ library DataTypes {
     //bit 152-167 liquidation protocol fee
     //bit 168-175 eMode category
     //bit 176-211 unbacked mint cap, unbackedMintCap == 0 => disabled
+    //bit 212-251 debt ceiling
+
     uint256 data;
   }
 

contracts/protocol/pool/DefaultReserveInterestRateStrategy.sol

@@ -4,10 +4,9 @@ pragma solidity 0.8.7;
 import {IERC20} from '../../dependencies/openzeppelin/contracts/IERC20.sol';
 import {WadRayMath} from '../libraries/math/WadRayMath.sol';
 import {PercentageMath} from '../libraries/math/PercentageMath.sol';
+import {DataTypes} from '../libraries/types/DataTypes.sol';
 import {IReserveInterestRateStrategy} from '../../interfaces/IReserveInterestRateStrategy.sol';
 import {IPoolAddressesProvider} from '../../interfaces/IPoolAddressesProvider.sol';
-import {IERC20} from '../../dependencies/openzeppelin/contracts/IERC20.sol';
-import {DataTypes} from '../libraries/types/DataTypes.sol';
 
 /**
  * @title DefaultReserveInterestRateStrategy contract
@@ -28,6 +27,10 @@ contract DefaultReserveInterestRateStrategy is IReserveInterestRateStrategy {
    **/
   uint256 public immutable OPTIMAL_UTILIZATION_RATE;
 
+  /**
+   * @dev This constant represents the optimal stable debt to total debt ratio of the reserve.
+   * Expressed in ray
+   */
   uint256 public immutable OPTIMAL_STABLE_TO_TOTAL_DEBT_RATIO;
 
   /**

contracts/protocol/pool/Pool.sol

@@ -17,13 +17,13 @@ import {BorrowLogic} from '../libraries/logic/BorrowLogic.sol';
 import {LiquidationLogic} from '../libraries/logic/LiquidationLogic.sol';
 import {ReserveConfiguration} from '../libraries/configuration/ReserveConfiguration.sol';
 import {DataTypes} from '../libraries/types/DataTypes.sol';
+import {BridgeLogic} from '../libraries/logic/BridgeLogic.sol';
 import {IERC20WithPermit} from '../../interfaces/IERC20WithPermit.sol';
 import {IPoolAddressesProvider} from '../../interfaces/IPoolAddressesProvider.sol';
 import {IAToken} from '../../interfaces/IAToken.sol';
 import {IPool} from '../../interfaces/IPool.sol';
 import {IACLManager} from '../../interfaces/IACLManager.sol';
 import {PoolStorage} from './PoolStorage.sol';
-import {BridgeLogic} from './../libraries/logic/BridgeLogic.sol';
 
 /**
  * @title Pool contract

contracts/protocol/tokenization/DelegationAwareAToken.sol

@@ -16,12 +16,6 @@ import {AToken} from './AToken.sol';
 contract DelegationAwareAToken is AToken {
   constructor(IPool pool) AToken(pool) {}
 
-  modifier onlyPoolAdmin() {
-    IACLManager aclManager = IACLManager(IPool(_pool).getAddressesProvider().getACLManager());
-    require(aclManager.isPoolAdmin(msg.sender), Errors.CALLER_NOT_POOL_ADMIN);
-    _;
-  }
-
   /**
    * @notice Delegates voting power of the underlying asset to a `delegatee` address
    * @param delegatee The address that will receive the delegation

contracts/protocol/tokenization/IncentivizedERC20.sol

@@ -4,12 +4,12 @@ pragma solidity 0.8.7;
 import {Context} from '../../dependencies/openzeppelin/contracts/Context.sol';
 import {IERC20} from '../../dependencies/openzeppelin/contracts/IERC20.sol';
 import {IERC20Detailed} from '../../dependencies/openzeppelin/contracts/IERC20Detailed.sol';
-import {IAaveIncentivesController} from '../../interfaces/IAaveIncentivesController.sol';
 import {Helpers} from '../libraries/helpers/Helpers.sol';
 import {WadRayMath} from '../libraries/math/WadRayMath.sol';
+import {Errors} from '../libraries/helpers/Errors.sol';
+import {IAaveIncentivesController} from '../../interfaces/IAaveIncentivesController.sol';
 import {IPoolAddressesProvider} from '../../interfaces/IPoolAddressesProvider.sol';
 import {IACLManager} from '../../interfaces/IACLManager.sol';
-import {Errors} from '../libraries/helpers/Errors.sol';
 
 /**
  * @title IncentivizedERC20
@@ -19,7 +19,7 @@ import {Errors} from '../libraries/helpers/Errors.sol';
 abstract contract IncentivizedERC20 is Context, IERC20, IERC20Detailed {
   using WadRayMath for uint256;
 
-  modifier onlyPoolAdmins() {
+  modifier onlyPoolAdmin() {
     IACLManager aclManager = IACLManager(_addressesProvider.getACLManager());
     require(aclManager.isPoolAdmin(msg.sender), Errors.CALLER_NOT_POOL_ADMIN);
     _;
@@ -28,7 +28,7 @@ abstract contract IncentivizedERC20 is Context, IERC20, IERC20Detailed {
   /**
    * @dev UserState - additionalData is a flexible field.
    * ATokens and VariableDebtTokens use this field store the index of the
-   * user's last deposit/withdrawl/borrow/repayment. StableDebtTokens use
+   * user's last supply/withdrawl/borrow/repayment. StableDebtTokens use
    * this field to store the user's stable rate.
    */
   struct UserState {
@@ -83,18 +83,18 @@ abstract contract IncentivizedERC20 is Context, IERC20, IERC20Detailed {
   }
 
   /**
-   * @notice Returns the address of the incentives controller contract
-   * @return Incentivescontroller
+   * @notice Returns the address of the Incentives Controller contract
+   * @return The address of the Incentives Controller
    **/
   function getIncentivesController() external view virtual returns (IAaveIncentivesController) {
     return _incentivesController;
   }
 
   /**
-   * @notice Sets a new incentives controller
+   * @notice Sets a new Incentives Controller
    * @param controller the new Incentives controller
    **/
-  function setIncentivesController(IAaveIncentivesController controller) external onlyPoolAdmins {
+  function setIncentivesController(IAaveIncentivesController controller) external onlyPoolAdmin {
     _incentivesController = controller;
   }
 

test-suites/helpers/utils/helpers.ts

@@ -21,7 +21,7 @@ export const getReserveData = async (
   const [reserveData, tokenAddresses, irStrategyAddress, reserveConfiguration, token] = await Promise.all([
     helper.getReserveData(reserve),
     helper.getReserveTokensAddresses(reserve),
-    helper.getIRStrategyAddress(reserve),
+    helper.getInterestRateStrategyAddress(reserve),
     helper.getReserveConfigurationData(reserve),
     getIErc20Detailed(reserve),
   ]);