Merge pull request #320 from aave/docs/319-improve-emodelogic-configuratiorlogic

Improve emodelogic and configuratorlogic natspec

Author: The-3D

contracts/interfaces/IPoolConfigurator.sol

@@ -264,10 +264,7 @@ interface IPoolConfigurator {
    * @param asset The address of the underlying asset of the reserve
    * @param enabled True if borrowing needs to be enabled, false otherwise
    **/
-  function setReserveBorrowing(
-    address asset,
-    bool enabled
-  ) external;
+  function setReserveBorrowing(address asset, bool enabled) external;
 
   /**
    * @notice Configures the reserve collateralization parameters

contracts/protocol/libraries/logic/ConfiguratorLogic.sol

@@ -48,6 +48,12 @@ library ConfiguratorLogic {
     address indexed implementation
   );
 
+  /**
+   * @notice Initialize a reserve by creating and initializing aToken, stable debt token and variable debt token
+   * @dev Emits the `ReserveInitialized` event
+   * @param pool The Pool in which the reserve will be initialized
+   * @param input The needed parameters for the initialization
+   */
   function executeInitReserve(IPool pool, ConfiguratorInputTypes.InitReserveInput calldata input)
     public
   {
@@ -120,6 +126,12 @@ library ConfiguratorLogic {
     );
   }
 
+  /**
+   * @notice Updates the aToken implementation and initializes it
+   * @dev Emits the `ATokenUpgraded` event
+   * @param cachedPool The Pool containing the reserve with the aToken
+   * @param input The parameters needed for the initialize call
+   */
   function executeUpdateAToken(
     IPool cachedPool,
     ConfiguratorInputTypes.UpdateATokenInput calldata input
@@ -144,6 +156,12 @@ library ConfiguratorLogic {
     emit ATokenUpgraded(input.asset, reserveData.aTokenAddress, input.implementation);
   }
 
+  /**
+   * @notice Updates the stable debt token implementation and initializes it
+   * @dev Emits the `StableDebtTokenUpgraded` event
+   * @param cachedPool The Pool containing the reserve with the stable debt token
+   * @param input The parameters needed for the initialize call
+   */
   function executeUpdateStableDebtToken(
     IPool cachedPool,
     ConfiguratorInputTypes.UpdateDebtTokenInput calldata input
@@ -175,6 +193,12 @@ library ConfiguratorLogic {
     );
   }
 
+  /**
+   * @notice Updates the variable debt token implementation and initializes it
+   * @dev Emits the `VariableDebtTokenUpgraded` event
+   * @param cachedPool The Pool containing the reserve with the variable debt token
+   * @param input The parameters needed for the initialize call
+   */
   function executeUpdateVariableDebtToken(
     IPool cachedPool,
     ConfiguratorInputTypes.UpdateDebtTokenInput calldata input
@@ -206,6 +230,12 @@ library ConfiguratorLogic {
     );
   }
 
+  /**
+   * @notice Creates a new proxy and initializes the implementation
+   * @param implementation The address of the implementation
+   * @param initParams The parameters that is passed to the implementation to initialize
+   * @return The address of initialized proxy
+   */
   function _initTokenWithProxy(address implementation, bytes memory initParams)
     internal
     returns (address)
@@ -219,6 +249,13 @@ library ConfiguratorLogic {
     return address(proxy);
   }
 
+  /**
+   * @notice Upgrades the implementation and makes call to the proxy
+   * @dev In the current plementation the call is used to initialize the new implementation.
+   * @param proxyAddress The address of the proxy
+   * @param implementation The address of the new implementation
+   * @param  initParams The parameters to the call after the upgrade
+   */
   function _upgradeTokenImplementation(
     address proxyAddress,
     address implementation,

contracts/protocol/libraries/logic/EModeLogic.sol

@@ -30,6 +30,17 @@ library EModeLogic {
   // See `IPool` for descriptions
   event UserEModeSet(address indexed user, uint8 categoryId);
 
+  /**
+   * @notice Updates the user efficiency mode category
+   * @dev Will revert if user is borrowing non-compatible asset or change will drop HF < HEALTH_FACTOR_LIQUIDATION_THRESHOLD
+   * @dev Emits the `UserEModeSet` event
+   * @param reserves The state of all the reserves
+   * @param reservesList The list of the addresses of all the active reserves
+   * @param eModeCategories The configuration of all the efficiency mode categories
+   * @param usersEModeCategory The state of all users efficiency mode category
+   * @param userConfig The user configuration mapping that tracks the supplied/borrowed assets
+   * @param params The additional parameters needed to execute the setUserEMode function
+   */
   function executeSetUserEMode(
     mapping(address => DataTypes.ReserveData) storage reserves,
     mapping(uint256 => address) storage reservesList,

test-suites/configurator.spec.ts

@@ -326,9 +326,7 @@ makeSuite('PoolConfigurator', (testEnv: TestEnv) => {
 
   it('Activates the ETH reserve for borrowing via risk admin', async () => {
     const { configurator, weth, helpersContract, riskAdmin } = testEnv;
-    expect(
-      await configurator.connect(riskAdmin.signer).setReserveBorrowing(weth.address, true)
-    )
+    expect(await configurator.connect(riskAdmin.signer).setReserveBorrowing(weth.address, true))
       .to.emit(configurator, 'ReserveBorrowing')
       .withArgs(weth.address, true);
 
@@ -432,7 +430,9 @@ makeSuite('PoolConfigurator', (testEnv: TestEnv) => {
   it('Disable stable borrow rate on the ETH reserve risk admin', async () => {
     const { configurator, helpersContract, weth, riskAdmin } = testEnv;
     expect(
-      await configurator.connect(riskAdmin.signer).setReserveStableRateBorrowing(weth.address, false)
+      await configurator
+        .connect(riskAdmin.signer)
+        .setReserveStableRateBorrowing(weth.address, false)
     )
       .to.emit(configurator, 'ReserveStableRateBorrowing')
       .withArgs(weth.address, false);

test-suites/interest-overflow.spec.ts

@@ -134,12 +134,7 @@ makeSuite('Interest Rate and Index Overflow', (testEnv) => {
         inputParams[i].liquidationThreshold,
         inputParams[i].liquidationBonus
       );
-    await configurator
-      .connect(poolAdmin.signer)
-      .setReserveBorrowing(
-        inputParams[i].asset,
-        true
-      );
+    await configurator.connect(poolAdmin.signer).setReserveBorrowing(inputParams[i].asset, true);
 
     await configurator
       .connect(poolAdmin.signer)