From 92a731ec2c536734924f5a55d3e6db0385b0c824 Mon Sep 17 00:00:00 2001
From: The3D <frangellaemilio@gmail.com>
Date: Wed, 25 Nov 2020 18:33:49 +0100
Subject: [PATCH] Updated libraries

---
 ...zableImmutableAdminUpgradeabilityProxy.sol |   3 +-
 .../VersionedInitializable.sol                |  12 +-
 .../configuration/ReserveConfiguration.sol    | 132 +++++++++---------
 .../configuration/UserConfiguration.sol       |  56 ++++----
 .../protocol/libraries/helpers/Errors.sol     |   2 +-
 .../protocol/libraries/helpers/Helpers.sol    |   9 +-
 .../protocol/libraries/logic/GenericLogic.sol | 125 ++++++++---------
 .../protocol/libraries/logic/ReserveLogic.sol |  86 ++++++------
 .../libraries/logic/ValidationLogic.sol       | 123 ++++++++--------
 .../protocol/libraries/math/MathUtils.sol     |  26 ++--
 .../libraries/math/PercentageMath.sol         |  18 +--
 .../protocol/libraries/math/WadRayMath.sol    |  48 +++----
 12 files changed, 319 insertions(+), 321 deletions(-)

diff --git a/contracts/protocol/libraries/aave-upgradeability/InitializableImmutableAdminUpgradeabilityProxy.sol b/contracts/protocol/libraries/aave-upgradeability/InitializableImmutableAdminUpgradeabilityProxy.sol
index 00d26f2e..d6478af9 100644
--- a/contracts/protocol/libraries/aave-upgradeability/InitializableImmutableAdminUpgradeabilityProxy.sol
+++ b/contracts/protocol/libraries/aave-upgradeability/InitializableImmutableAdminUpgradeabilityProxy.sol
@@ -6,8 +6,7 @@ import '../../../dependencies/openzeppelin/upgradeability/InitializableUpgradeab
 
 /**
  * @title InitializableAdminUpgradeabilityProxy
- * @dev Extends from BaseAdminUpgradeabilityProxy with an initializer for
- * initializing the implementation, admin, and init data.
+ * @dev Extends BaseAdminUpgradeabilityProxy with an initializer function
  */
 contract InitializableImmutableAdminUpgradeabilityProxy is
   BaseImmutableAdminUpgradeabilityProxy,
diff --git a/contracts/protocol/libraries/aave-upgradeability/VersionedInitializable.sol b/contracts/protocol/libraries/aave-upgradeability/VersionedInitializable.sol
index 0e9d83fb..f2b73b8e 100644
--- a/contracts/protocol/libraries/aave-upgradeability/VersionedInitializable.sol
+++ b/contracts/protocol/libraries/aave-upgradeability/VersionedInitializable.sol
@@ -4,7 +4,7 @@ pragma solidity 0.6.12;
 /**
  * @title VersionedInitializable
  *
- * @dev Helper contract to support initializer functions. To use it, replace
+ * @dev Helper contract to implement initializer functions. To use it, replace
  * the constructor with a function that has the `initializer` modifier.
  * WARNING: Unlike constructors, initializer functions must be manually
  * invoked. This applies both to deploying an Initializable contract, as well
@@ -49,11 +49,15 @@ abstract contract VersionedInitializable {
     }
   }
 
-  /// @dev returns the revision number of the contract.
-  /// Needs to be defined in the inherited class as a constant.
+  /**
+  * @dev returns the revision number of the contract
+  * Needs to be defined in the inherited class as a constant.
+  **/ 
   function getRevision() internal pure virtual returns (uint256);
 
-  /// @dev Returns true if and only if the function is running in the constructor
+  /**
+  * @dev Returns true if and only if the function is running in the constructor
+  **/ 
   function isConstructor() private view returns (bool) {
     // extcodesize checks the size of the code stored in an address, and
     // address returns the current address. Since the code is still not
diff --git a/contracts/protocol/libraries/configuration/ReserveConfiguration.sol b/contracts/protocol/libraries/configuration/ReserveConfiguration.sol
index 39df878b..60076a6f 100644
--- a/contracts/protocol/libraries/configuration/ReserveConfiguration.sol
+++ b/contracts/protocol/libraries/configuration/ReserveConfiguration.sol
@@ -20,7 +20,7 @@ library ReserveConfiguration {
   uint256 constant STABLE_BORROWING_MASK =      0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFFFFFFFFF; // prettier-ignore
   uint256 constant RESERVE_FACTOR_MASK =        0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF0000FFFFFFFFFFFFFFFF; // prettier-ignore
 
-  /// @dev For the LTV, the start bit is 0 (up to 15), but we don't declare it as for 0 no bit movement is needed
+  /// @dev For the LTV, the start bit is 0 (up to 15), hence no bitshifting is needed
   uint256 constant LIQUIDATION_THRESHOLD_START_BIT_POSITION = 16;
   uint256 constant LIQUIDATION_BONUS_START_BIT_POSITION = 32;
   uint256 constant RESERVE_DECIMALS_START_BIT_POSITION = 48;
@@ -37,8 +37,8 @@ library ReserveConfiguration {
   uint256 constant MAX_VALID_RESERVE_FACTOR = 65535;
 
   /**
-   * @dev sets the Loan to Value of the reserve
-   * @param self the reserve configuration
+   * @dev Sets the Loan to Value of the reserve
+   * @param self The reserve configuration
    * @param ltv the new ltv
    **/
   function setLtv(DataTypes.ReserveConfigurationMap memory self, uint256 ltv) internal pure {
@@ -48,18 +48,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the Loan to Value of the reserve
-   * @param self the reserve configuration
-   * @return the loan to value
+   * @dev Gets the Loan to Value of the reserve
+   * @param self The reserve configuration
+   * @return The loan to value
    **/
   function getLtv(DataTypes.ReserveConfigurationMap storage self) internal view returns (uint256) {
     return self.data & ~LTV_MASK;
   }
 
   /**
-   * @dev sets the liquidation threshold of the reserve
-   * @param self the reserve configuration
-   * @param threshold the new liquidation threshold
+   * @dev Sets the liquidation threshold of the reserve
+   * @param self The reserve configuration
+   * @param threshold The new liquidation threshold
    **/
   function setLiquidationThreshold(DataTypes.ReserveConfigurationMap memory self, uint256 threshold)
     internal
@@ -73,9 +73,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the liquidation threshold of the reserve
-   * @param self the reserve configuration
-   * @return the liquidation threshold
+   * @dev Gets the liquidation threshold of the reserve
+   * @param self The reserve configuration
+   * @return The liquidation threshold
    **/
   function getLiquidationThreshold(DataTypes.ReserveConfigurationMap storage self)
     internal
@@ -86,9 +86,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev sets the liquidation bonus of the reserve
-   * @param self the reserve configuration
-   * @param bonus the new liquidation bonus
+   * @dev Sets the liquidation bonus of the reserve
+   * @param self The reserve configuration
+   * @param bonus The new liquidation bonus
    **/
   function setLiquidationBonus(DataTypes.ReserveConfigurationMap memory self, uint256 bonus) internal pure {
     require(bonus <= MAX_VALID_LIQUIDATION_BONUS, Errors.RC_INVALID_LIQ_BONUS);
@@ -99,9 +99,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the liquidation bonus of the reserve
-   * @param self the reserve configuration
-   * @return the liquidation bonus
+   * @dev Gets the liquidation bonus of the reserve
+   * @param self The reserve configuration
+   * @return The liquidation bonus
    **/
   function getLiquidationBonus(DataTypes.ReserveConfigurationMap storage self)
     internal
@@ -112,9 +112,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev sets the decimals of the underlying asset of the reserve
-   * @param self the reserve configuration
-   * @param decimals the decimals
+   * @dev Sets the decimals of the underlying asset of the reserve
+   * @param self The reserve configuration
+   * @param decimals The decimals
    **/
   function setDecimals(DataTypes.ReserveConfigurationMap memory self, uint256 decimals) internal pure {
     require(decimals <= MAX_VALID_DECIMALS, Errors.RC_INVALID_DECIMALS);
@@ -123,18 +123,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the decimals of the underlying asset of the reserve
-   * @param self the reserve configuration
-   * @return the decimals of the asset
+   * @dev Gets the decimals of the underlying asset of the reserve
+   * @param self The reserve configuration
+   * @return The decimals of the asset
    **/
   function getDecimals(DataTypes.ReserveConfigurationMap storage self) internal view returns (uint256) {
     return (self.data & ~DECIMALS_MASK) >> RESERVE_DECIMALS_START_BIT_POSITION;
   }
 
   /**
-   * @dev sets the active state of the reserve
-   * @param self the reserve configuration
-   * @param active the active state
+   * @dev Sets the active state of the reserve
+   * @param self The reserve configuration
+   * @param active The active state
    **/
   function setActive(DataTypes.ReserveConfigurationMap memory self, bool active) internal pure {
     self.data =
@@ -143,18 +143,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the active state of the reserve
-   * @param self the reserve configuration
-   * @return the active state
+   * @dev Gets the active state of the reserve
+   * @param self The reserve configuration
+   * @return The active state
    **/
   function getActive(DataTypes.ReserveConfigurationMap storage self) internal view returns (bool) {
     return (self.data & ~ACTIVE_MASK) != 0;
   }
 
   /**
-   * @dev sets the frozen state of the reserve
-   * @param self the reserve configuration
-   * @param frozen the frozen state
+   * @dev Sets the frozen state of the reserve
+   * @param self The reserve configuration
+   * @param frozen The frozen state
    **/
   function setFrozen(DataTypes.ReserveConfigurationMap memory self, bool frozen) internal pure {
     self.data =
@@ -163,18 +163,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the frozen state of the reserve
-   * @param self the reserve configuration
-   * @return the frozen state
+   * @dev Gets the frozen state of the reserve
+   * @param self The reserve configuration
+   * @return The frozen state
    **/
   function getFrozen(DataTypes.ReserveConfigurationMap storage self) internal view returns (bool) {
     return (self.data & ~FROZEN_MASK) != 0;
   }
 
   /**
-   * @dev enables or disables borrowing on the reserve
-   * @param self the reserve configuration
-   * @param enabled true if the borrowing needs to be enabled, false otherwise
+   * @dev Enables or disables borrowing on the reserve
+   * @param self The reserve configuration
+   * @param enabled True if the borrowing needs to be enabled, false otherwise
    **/
   function setBorrowingEnabled(DataTypes.ReserveConfigurationMap memory self, bool enabled) internal pure {
     self.data =
@@ -183,18 +183,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the borrowing state of the reserve
-   * @param self the reserve configuration
-   * @return the borrowing state
+   * @dev Gets the borrowing state of the reserve
+   * @param self The reserve configuration
+   * @return The borrowing state
    **/
   function getBorrowingEnabled(DataTypes.ReserveConfigurationMap storage self) internal view returns (bool) {
     return (self.data & ~BORROWING_MASK) != 0;
   }
 
   /**
-   * @dev enables or disables stable rate borrowing on the reserve
-   * @param self the reserve configuration
-   * @param enabled true if the stable rate borrowing needs to be enabled, false otherwise
+   * @dev Enables or disables stable rate borrowing on the reserve
+   * @param self The reserve configuration
+   * @param enabled True if the stable rate borrowing needs to be enabled, false otherwise
    **/
   function setStableRateBorrowingEnabled(DataTypes.ReserveConfigurationMap memory self, bool enabled)
     internal
@@ -206,9 +206,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the stable rate borrowing state of the reserve
-   * @param self the reserve configuration
-   * @return the stable rate borrowing state
+   * @dev Gets the stable rate borrowing state of the reserve
+   * @param self The reserve configuration
+   * @return The stable rate borrowing state
    **/
   function getStableRateBorrowingEnabled(DataTypes.ReserveConfigurationMap storage self)
     internal
@@ -219,9 +219,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev sets the reserve factor of the reserve
-   * @param self the reserve configuration
-   * @param reserveFactor the reserve factor
+   * @dev Sets the reserve factor of the reserve
+   * @param self The reserve configuration
+   * @param reserveFactor The reserve factor
    **/
   function setReserveFactor(DataTypes.ReserveConfigurationMap memory self, uint256 reserveFactor)
     internal
@@ -235,18 +235,18 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the reserve factor of the reserve
-   * @param self the reserve configuration
-   * @return the reserve factor
+   * @dev Gets the reserve factor of the reserve
+   * @param self The reserve configuration
+   * @return The reserve factor
    **/
   function getReserveFactor(DataTypes.ReserveConfigurationMap storage self) internal view returns (uint256) {
     return (self.data & ~RESERVE_FACTOR_MASK) >> RESERVE_FACTOR_START_BIT_POSITION;
   }
 
   /**
-   * @dev gets the configuration flags of the reserve
-   * @param self the reserve configuration
-   * @return the state flags representing active, frozen, borrowing enabled, stableRateBorrowing enabled
+   * @dev Gets the configuration flags of the reserve
+   * @param self The reserve configuration
+   * @return The state flags representing active, frozen, borrowing enabled, stableRateBorrowing enabled
    **/
   function getFlags(DataTypes.ReserveConfigurationMap storage self)
     internal
@@ -269,9 +269,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the configuration paramters of the reserve
-   * @param self the reserve configuration
-   * @return the state params representing ltv, liquidation threshold, liquidation bonus, the reserve decimals
+   * @dev Gets the configuration paramters of the reserve
+   * @param self The reserve configuration
+   * @return The state params representing ltv, liquidation threshold, liquidation bonus, the reserve decimals
    **/
   function getParams(DataTypes.ReserveConfigurationMap storage self)
     internal
@@ -296,9 +296,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the configuration paramters of the reserve from a memory object
-   * @param self the reserve configuration
-   * @return the state params representing ltv, liquidation threshold, liquidation bonus, the reserve decimals
+   * @dev Gets the configuration paramters of the reserve from a memory object
+   * @param self The reserve configuration
+   * @return The state params representing ltv, liquidation threshold, liquidation bonus, the reserve decimals
    **/
   function getParamsMemory(DataTypes.ReserveConfigurationMap memory self)
     internal
@@ -321,9 +321,9 @@ library ReserveConfiguration {
   }
 
   /**
-   * @dev gets the configuration flags of the reserve from a memory object
-   * @param self the reserve configuration
-   * @return the state flags representing active, frozen, borrowing enabled, stableRateBorrowing enabled
+   * @dev Gets the configuration flags of the reserve from a memory object
+   * @param self The reserve configuration
+   * @return The state flags representing active, frozen, borrowing enabled, stableRateBorrowing enabled
    **/
   function getFlagsMemory(DataTypes.ReserveConfigurationMap memory self)
     internal
diff --git a/contracts/protocol/libraries/configuration/UserConfiguration.sol b/contracts/protocol/libraries/configuration/UserConfiguration.sol
index b4af79ad..b56f6140 100644
--- a/contracts/protocol/libraries/configuration/UserConfiguration.sol
+++ b/contracts/protocol/libraries/configuration/UserConfiguration.sol
@@ -14,10 +14,10 @@ library UserConfiguration {
     0x5555555555555555555555555555555555555555555555555555555555555555;
 
   /**
-   * @dev sets if the user is borrowing the reserve identified by reserveIndex
-   * @param self the configuration object
-   * @param reserveIndex the index of the reserve in the bitmap
-   * @param borrowing true if the user is borrowing the reserve, false otherwise
+   * @dev Sets if the user is borrowing the reserve identified by reserveIndex
+   * @param self The configuration object
+   * @param reserveIndex The index of the reserve in the bitmap
+   * @param borrowing True if the user is borrowing the reserve, false otherwise
    **/
   function setBorrowing(
     DataTypes.UserConfigurationMap storage self,
@@ -31,27 +31,27 @@ library UserConfiguration {
   }
 
   /**
-   * @dev sets if the user is using as collateral the reserve identified by reserveIndex
-   * @param self the configuration object
-   * @param reserveIndex the index of the reserve in the bitmap
-   * @param _usingAsCollateral true if the user is usin the reserve as collateral, false otherwise
+   * @dev Sets if the user is using as collateral the reserve identified by reserveIndex
+   * @param self The configuration object
+   * @param reserveIndex The index of the reserve in the bitmap
+   * @param usingAsCollateral True if the user is usin the reserve as collateral, false otherwise
    **/
   function setUsingAsCollateral(
     DataTypes.UserConfigurationMap storage self,
     uint256 reserveIndex,
-    bool _usingAsCollateral
+    bool usingAsCollateral
   ) internal {
     require(reserveIndex < 128, Errors.UL_INVALID_INDEX);
     self.data =
       (self.data & ~(1 << (reserveIndex * 2 + 1))) |
-      (uint256(_usingAsCollateral ? 1 : 0) << (reserveIndex * 2 + 1));
+      (uint256(usingAsCollateral ? 1 : 0) << (reserveIndex * 2 + 1));
   }
 
   /**
-   * @dev used to validate if a user has been using the reserve for borrowing or as collateral
-   * @param self the configuration object
-   * @param reserveIndex the index of the reserve in the bitmap
-   * @return true if the user has been using a reserve for borrowing or as collateral, false otherwise
+   * @dev Used to validate if a user has been using the reserve for borrowing or as collateral
+   * @param self The configuration object
+   * @param reserveIndex The index of the reserve in the bitmap
+   * @return True if the user has been using a reserve for borrowing or as collateral, false otherwise
    **/
   function isUsingAsCollateralOrBorrowing(DataTypes.UserConfigurationMap memory self, uint256 reserveIndex)
     internal
@@ -63,10 +63,10 @@ library UserConfiguration {
   }
 
   /**
-   * @dev used to validate if a user has been using the reserve for borrowing
-   * @param self the configuration object
-   * @param reserveIndex the index of the reserve in the bitmap
-   * @return true if the user has been using a reserve for borrowing, false otherwise
+   * @dev Used to validate if a user has been using the reserve for borrowing
+   * @param self The configuration object
+   * @param reserveIndex The index of the reserve in the bitmap
+   * @return True if the user has been using a reserve for borrowing, false otherwise
    **/
   function isBorrowing(DataTypes.UserConfigurationMap memory self, uint256 reserveIndex)
     internal
@@ -78,10 +78,10 @@ library UserConfiguration {
   }
 
   /**
-   * @dev used to validate if a user has been using the reserve as collateral
-   * @param self the configuration object
-   * @param reserveIndex the index of the reserve in the bitmap
-   * @return true if the user has been using a reserve as collateral, false otherwise
+   * @dev Used to validate if a user has been using the reserve as collateral
+   * @param self The configuration object
+   * @param reserveIndex The index of the reserve in the bitmap
+   * @return True if the user has been using a reserve as collateral, false otherwise
    **/
   function isUsingAsCollateral(DataTypes.UserConfigurationMap memory self, uint256 reserveIndex)
     internal
@@ -93,18 +93,18 @@ library UserConfiguration {
   }
 
   /**
-   * @dev used to validate if a user has been borrowing from any reserve
-   * @param self the configuration object
-   * @return true if the user has been borrowing any reserve, false otherwise
+   * @dev Used to validate if a user has been borrowing from any reserve
+   * @param self The configuration object
+   * @return True if the user has been borrowing any reserve, false otherwise
    **/
   function isBorrowingAny(DataTypes.UserConfigurationMap memory self) internal pure returns (bool) {
     return self.data & BORROWING_MASK != 0;
   }
 
   /**
-   * @dev used to validate if a user has not been using any reserve
-   * @param self the configuration object
-   * @return true if the user has been borrowing any reserve, false otherwise
+   * @dev Used to validate if a user has not been using any reserve
+   * @param self The configuration object
+   * @return True if the user has been borrowing any reserve, false otherwise
    **/
   function isEmpty(DataTypes.UserConfigurationMap memory self) internal pure returns (bool) {
     return self.data == 0;
diff --git a/contracts/protocol/libraries/helpers/Errors.sol b/contracts/protocol/libraries/helpers/Errors.sol
index ef6fa212..8756d797 100644
--- a/contracts/protocol/libraries/helpers/Errors.sol
+++ b/contracts/protocol/libraries/helpers/Errors.sol
@@ -4,7 +4,7 @@ pragma solidity 0.6.12;
 /**
  * @title Errors library
  * @author Aave
- * @notice Implements error messages.
+ * @notice Defines the error messages emitted by the different contracts of the Aave protocol
  * @dev Error messages prefix glossary:
  *  - VL = ValidationLogic
  *  - MATH = Math libraries
diff --git a/contracts/protocol/libraries/helpers/Helpers.sol b/contracts/protocol/libraries/helpers/Helpers.sol
index b21249e2..b0117ef7 100644
--- a/contracts/protocol/libraries/helpers/Helpers.sol
+++ b/contracts/protocol/libraries/helpers/Helpers.sol
@@ -7,14 +7,13 @@ import {DataTypes} from '../types/DataTypes.sol';
 /**
  * @title Helpers library
  * @author Aave
- * @notice Implements calculation helpers.
  */
 library Helpers {
   /**
-   * @dev fetches the user current stable and variable debt balances
-   * @param user the user
-   * @param reserve the reserve object
-   * @return the stable and variable debt balance
+   * @dev Fetches the user current stable and variable debt balances
+   * @param user The user address
+   * @param reserve The reserve data object
+   * @return The stable and variable debt balance
    **/
   function getUserCurrentDebt(address user, DataTypes.ReserveData storage reserve)
     internal
diff --git a/contracts/protocol/libraries/logic/GenericLogic.sol b/contracts/protocol/libraries/logic/GenericLogic.sol
index e8ee263f..e921ec52 100644
--- a/contracts/protocol/libraries/logic/GenericLogic.sol
+++ b/contracts/protocol/libraries/logic/GenericLogic.sol
@@ -15,7 +15,7 @@ import {DataTypes} from '../types/DataTypes.sol';
 /**
  * @title GenericLogic library
  * @author Aave
- * @title Implements protocol-level logic to check the status of the user across all the reserves
+ * @title Implements protocol-level logic to calculate and validate the state of a user
  */
 library GenericLogic {
   using ReserveLogic for DataTypes.ReserveData;
@@ -30,10 +30,10 @@ library GenericLogic {
   struct balanceDecreaseAllowedLocalVars {
     uint256 decimals;
     uint256 liquidationThreshold;
-    uint256 collateralBalanceETH;
-    uint256 borrowBalanceETH;
+    uint256 totalCollateralInETH;
+    uint256 totalDebtInETH;
     uint256 avgLiquidationThreshold;
-    uint256 amountToDecreaseETH;
+    uint256 amountToDecreaseInETH;
     uint256 collateralBalanceAfterDecrease;
     uint256 liquidationThresholdAfterDecrease;
     uint256 healthFactorAfterDecrease;
@@ -41,15 +41,15 @@ library GenericLogic {
   }
 
   /**
-   * @dev check if a specific balance decrease is allowed
+   * @dev Checks if a specific balance decrease is allowed
    * (i.e. doesn't bring the user borrow position health factor under HEALTH_FACTOR_LIQUIDATION_THRESHOLD)
-   * @param asset the address of the reserve
-   * @param user the address of the user
-   * @param amount the amount to decrease
-   * @param reservesData the data of all the reserves
-   * @param userConfig the user configuration
-   * @param reserves the list of all the active reserves
-   * @param oracle the address of the oracle contract
+   * @param asset The address of the underlying asset of the reserve
+   * @param user The address of the user
+   * @param amount The amount to decrease
+   * @param reservesData The data of all the reserves
+   * @param userConfig The user configuration
+   * @param reserves The list of all the active reserves
+   * @param oracle The address of the oracle contract
    * @return true if the decrease of the balance is allowed
    **/
   function balanceDecreaseAllowed(
@@ -65,7 +65,7 @@ library GenericLogic {
     if (!userConfig.isBorrowingAny() || !userConfig.isUsingAsCollateral(reservesData[asset].id)) {
       return true;
     }
-
+    
     balanceDecreaseAllowedLocalVars memory vars;
 
     (, vars.liquidationThreshold, , vars.decimals, ) = reservesData[asset]
@@ -73,26 +73,26 @@ library GenericLogic {
       .getParams();
 
     if (vars.liquidationThreshold == 0) {
-      return true; //if reserve is not used as collateral, no reasons to block the transfer
+      return true; 
     }
 
     (
-      vars.collateralBalanceETH,
-      vars.borrowBalanceETH,
+      vars.totalCollateralInETH,
+      vars.totalDebtInETH,
       ,
       vars.avgLiquidationThreshold,
 
     ) = calculateUserAccountData(user, reservesData, userConfig, reserves, reservesCount, oracle);
 
-    if (vars.borrowBalanceETH == 0) {
-      return true; //no borrows - no reasons to block the transfer
+    if (vars.totalDebtInETH == 0) {
+      return true;
     }
 
-    vars.amountToDecreaseETH = IPriceOracleGetter(oracle).getAssetPrice(asset).mul(amount).div(
+    vars.amountToDecreaseInETH = IPriceOracleGetter(oracle).getAssetPrice(asset).mul(amount).div(
       10**vars.decimals
     );
 
-    vars.collateralBalanceAfterDecrease = vars.collateralBalanceETH.sub(vars.amountToDecreaseETH);
+    vars.collateralBalanceAfterDecrease = vars.totalCollateralInETH.sub(vars.amountToDecreaseInETH);
 
     //if there is a borrow, there can't be 0 collateral
     if (vars.collateralBalanceAfterDecrease == 0) {
@@ -100,15 +100,15 @@ library GenericLogic {
     }
 
     vars.liquidationThresholdAfterDecrease = vars
-      .collateralBalanceETH
+      .totalCollateralInETH
       .mul(vars.avgLiquidationThreshold)
-      .sub(vars.amountToDecreaseETH.mul(vars.liquidationThreshold))
+      .sub(vars.amountToDecreaseInETH.mul(vars.liquidationThreshold))
       .div(vars.collateralBalanceAfterDecrease);
 
     uint256 healthFactorAfterDecrease =
       calculateHealthFactorFromBalances(
         vars.collateralBalanceAfterDecrease,
-        vars.borrowBalanceETH,
+        vars.totalDebtInETH,
         vars.liquidationThresholdAfterDecrease
       );
 
@@ -125,9 +125,8 @@ library GenericLogic {
     uint256 liquidationThreshold;
     uint256 i;
     uint256 healthFactor;
-    uint256 totalCollateralBalanceETH;
-    uint256 totalBorrowBalanceETH;
-    uint256 totalFeesETH;
+    uint256 totalCollateralInETH;
+    uint256 totalDebtInETH;
     uint256 avgLtv;
     uint256 avgLiquidationThreshold;
     uint256 reservesLength;
@@ -138,16 +137,15 @@ library GenericLogic {
   }
 
   /**
-   * @dev calculates the user data across the reserves.
+   * @dev Calculates the user data across the reserves.
    * this includes the total liquidity/collateral/borrow balances in ETH,
    * the average Loan To Value, the average Liquidation Ratio, and the Health factor.
-   * @param user the address of the user
-   * @param reservesData data of all the reserves
-   * @param userConfig the configuration of the user
-   * @param reserves the list of the available reserves
-   * @param oracle the price oracle address
-   * @return the total collateral and total borrow balance of the user in ETH, the avg ltv and liquidation threshold and the HF
-   * also the average Ltv, liquidation threshold, and the health factor
+   * @param user The address of the user
+   * @param reservesData Data of all the reserves
+   * @param userConfig The configuration of the user
+   * @param reserves The list of the available reserves
+   * @param oracle The price oracle address
+   * @return The total collateral and total debt of the user in ETH, the avg ltv, liquidation threshold and the HF
    **/
   function calculateUserAccountData(
     address user,
@@ -193,7 +191,7 @@ library GenericLogic {
         uint256 liquidityBalanceETH =
           vars.reserveUnitPrice.mul(vars.compoundedLiquidityBalance).div(vars.tokenUnit);
 
-        vars.totalCollateralBalanceETH = vars.totalCollateralBalanceETH.add(liquidityBalanceETH);
+        vars.totalCollateralInETH = vars.totalCollateralInETH.add(liquidityBalanceETH);
 
         vars.avgLtv = vars.avgLtv.add(liquidityBalanceETH.mul(vars.ltv));
         vars.avgLiquidationThreshold = vars.avgLiquidationThreshold.add(
@@ -209,27 +207,27 @@ library GenericLogic {
           IERC20(currentReserve.variableDebtTokenAddress).balanceOf(user)
         );
 
-        vars.totalBorrowBalanceETH = vars.totalBorrowBalanceETH.add(
+        vars.totalDebtInETH = vars.totalDebtInETH.add(
           vars.reserveUnitPrice.mul(vars.compoundedBorrowBalance).div(vars.tokenUnit)
         );
       }
     }
 
-    vars.avgLtv = vars.totalCollateralBalanceETH > 0
-      ? vars.avgLtv.div(vars.totalCollateralBalanceETH)
+    vars.avgLtv = vars.totalCollateralInETH > 0
+      ? vars.avgLtv.div(vars.totalCollateralInETH)
       : 0;
-    vars.avgLiquidationThreshold = vars.totalCollateralBalanceETH > 0
-      ? vars.avgLiquidationThreshold.div(vars.totalCollateralBalanceETH)
+    vars.avgLiquidationThreshold = vars.totalCollateralInETH > 0
+      ? vars.avgLiquidationThreshold.div(vars.totalCollateralInETH)
       : 0;
 
     vars.healthFactor = calculateHealthFactorFromBalances(
-      vars.totalCollateralBalanceETH,
-      vars.totalBorrowBalanceETH,
+      vars.totalCollateralInETH,
+      vars.totalDebtInETH,
       vars.avgLiquidationThreshold
     );
     return (
-      vars.totalCollateralBalanceETH,
-      vars.totalBorrowBalanceETH,
+      vars.totalCollateralInETH,
+      vars.totalDebtInETH,
       vars.avgLtv,
       vars.avgLiquidationThreshold,
       vars.healthFactor
@@ -237,43 +235,44 @@ library GenericLogic {
   }
 
   /**
-   * @dev calculates the health factor from the corresponding balances
-   * @param collateralBalanceETH the total collateral balance in ETH
-   * @param borrowBalanceETH the total borrow balance in ETH
-   * @param liquidationThreshold the avg liquidation threshold
-   * @return the health factor calculated from the balances provided
+   * @dev Calculates the health factor from the corresponding balances
+   * @param totalCollateralInETH The total collateral in ETH
+   * @param totalDebtInETH The total debt in ETH
+   * @param liquidationThreshold The avg liquidation threshold
+   * @return The health factor calculated from the balances provided
    **/
   function calculateHealthFactorFromBalances(
-    uint256 collateralBalanceETH,
-    uint256 borrowBalanceETH,
+    uint256 totalCollateralInETH,
+    uint256 totalDebtInETH,
     uint256 liquidationThreshold
   ) internal pure returns (uint256) {
-    if (borrowBalanceETH == 0) return uint256(-1);
+    if (totalDebtInETH == 0) return uint256(-1);
 
-    return (collateralBalanceETH.percentMul(liquidationThreshold)).wadDiv(borrowBalanceETH);
+    return (totalCollateralInETH.percentMul(liquidationThreshold)).wadDiv(totalDebtInETH);
   }
 
   /**
-   * @dev calculates the equivalent amount in ETH that an user can borrow, depending on the available collateral and the
-   * average Loan To Value.
-   * @param collateralBalanceETH the total collateral balance
-   * @param borrowBalanceETH the total borrow balance
-   * @param ltv the average loan to value
+   * @dev Calculates the equivalent amount in ETH that an user can borrow, depending on the available collateral and the
+   * average Loan To Value
+   * @param totalCollateralInETH The total collateral in ETH
+   * @param totalDebtInETH The total borrow balance
+   * @param ltv The average loan to value
    * @return the amount available to borrow in ETH for the user
    **/
 
   function calculateAvailableBorrowsETH(
-    uint256 collateralBalanceETH,
-    uint256 borrowBalanceETH,
+    uint256 totalCollateralInETH,
+    uint256 totalDebtInETH,
     uint256 ltv
   ) internal pure returns (uint256) {
-    uint256 availableBorrowsETH = collateralBalanceETH.percentMul(ltv); //ltv is in percentage
+    
+    uint256 availableBorrowsETH = totalCollateralInETH.percentMul(ltv); 
 
-    if (availableBorrowsETH < borrowBalanceETH) {
+    if (availableBorrowsETH < totalDebtInETH) {
       return 0;
     }
 
-    availableBorrowsETH = availableBorrowsETH.sub(borrowBalanceETH);
+    availableBorrowsETH = availableBorrowsETH.sub(totalDebtInETH);
     return availableBorrowsETH;
   }
 }
diff --git a/contracts/protocol/libraries/logic/ReserveLogic.sol b/contracts/protocol/libraries/logic/ReserveLogic.sol
index 7a73be5b..14611df6 100644
--- a/contracts/protocol/libraries/logic/ReserveLogic.sol
+++ b/contracts/protocol/libraries/logic/ReserveLogic.sol
@@ -18,7 +18,7 @@ import {DataTypes} from '../types/DataTypes.sol';
 /**
  * @title ReserveLogic library
  * @author Aave
- * @notice Implements the logic to update the state of the reserves
+ * @notice Implements the logic to update the reserves state
  */
 library ReserveLogic {
   using SafeMath for uint256;
@@ -28,15 +28,15 @@ library ReserveLogic {
 
   /**
    * @dev Emitted when the state of a reserve is updated
-   * @param reserve the address of the reserve
-   * @param liquidityRate the new liquidity rate
-   * @param stableBorrowRate the new stable borrow rate
-   * @param variableBorrowRate the new variable borrow rate
-   * @param liquidityIndex the new liquidity index
-   * @param variableBorrowIndex the new variable borrow index
+   * @param asset The address of the underlying asset of the reserve
+   * @param liquidityRate The new liquidity rate
+   * @param stableBorrowRate The new stable borrow rate
+   * @param variableBorrowRate The new variable borrow rate
+   * @param liquidityIndex The new liquidity index
+   * @param variableBorrowIndex The new variable borrow index
    **/
   event ReserveDataUpdated(
-    address indexed reserve,
+    address indexed asset,
     uint256 liquidityRate,
     uint256 stableBorrowRate,
     uint256 variableBorrowRate,
@@ -48,10 +48,10 @@ library ReserveLogic {
   using ReserveConfiguration for DataTypes.ReserveConfigurationMap;
 
   /**
-   * @dev returns the ongoing normalized income for the reserve.
-   * a value of 1e27 means there is no income. As time passes, the income is accrued.
-   * A value of 2*1e27 means for each unit of asset one unit of income has been accrued.
-   * @param reserve the reserve object
+   * @dev Returns the ongoing normalized income for the reserve
+   * A value of 1e27 means there is no income. As time passes, the income is accrued
+   * A value of 2*1e27 means for each unit of asset one unit of income has been accrued
+   * @param reserve The reserve object
    * @return the normalized income. expressed in ray
    **/
   function getNormalizedIncome(DataTypes.ReserveData storage reserve)
@@ -76,11 +76,11 @@ library ReserveLogic {
   }
 
   /**
-   * @dev returns the ongoing normalized variable debt for the reserve.
-   * a value of 1e27 means there is no debt. As time passes, the income is accrued.
-   * A value of 2*1e27 means that the debt of the reserve is double the initial amount.
-   * @param reserve the reserve object
-   * @return the normalized variable debt. expressed in ray
+   * @dev Returns the ongoing normalized variable debt for the reserve
+   * A value of 1e27 means there is no debt. As time passes, the income is accrued
+   * A value of 2*1e27 means that for each unit of debt, one unit worth of interest has been accumulated
+   * @param reserve The reserve object
+   * @return The normalized variable debt. expressed in ray
    **/
   function getNormalizedDebt(DataTypes.ReserveData storage reserve)
     internal
@@ -104,8 +104,7 @@ library ReserveLogic {
   }
 
   /**
-   * @dev Updates the liquidity cumulative index Ci and variable borrow cumulative index Bvc. Refer to the whitepaper for
-   * a formal specification.
+   * @dev Updates the liquidity cumulative index and the variable borrow index.
    * @param reserve the reserve object
    **/
   function updateState(DataTypes.ReserveData storage reserve) internal {
@@ -135,11 +134,11 @@ library ReserveLogic {
   }
 
   /**
-   * @dev accumulates a predefined amount of asset to the reserve as a fixed, one time income. Used for example to accumulate
-   * the flashloan fee to the reserve, and spread it through the depositors.
-   * @param reserve the reserve object
-   * @param totalLiquidity the total liquidity available in the reserve
-   * @param amount the amount to accomulate
+   * @dev Accumulates a predefined amount of asset to the reserve as a fixed, instantaneous income. Used for example to accumulate
+   * the flashloan fee to the reserve, and spread it between all the depositors
+   * @param reserve The reserve object
+   * @param totalLiquidity The total liquidity available in the reserve
+   * @param amount The amount to accomulate
    **/
   function cumulateToLiquidityIndex(
     DataTypes.ReserveData storage reserve,
@@ -157,10 +156,10 @@ library ReserveLogic {
   }
 
   /**
-   * @dev initializes a reserve
-   * @param reserve the reserve object
-   * @param aTokenAddress the address of the overlying atoken contract
-   * @param interestRateStrategyAddress the address of the interest rate strategy contract
+   * @dev Initializes a reserve
+   * @param reserve The reserve object
+   * @param aTokenAddress The address of the overlying atoken contract
+   * @param interestRateStrategyAddress The address of the interest rate strategy contract
    **/
   function init(
     DataTypes.ReserveData storage reserve,
@@ -191,11 +190,10 @@ library ReserveLogic {
   }
 
   /**
-   * @dev Updates the reserve current stable borrow rate Rf, the current variable borrow rate Rv and the current liquidity rate Rl.
-   * Also updates the lastUpdateTimestamp value. Please refer to the whitepaper for further information.
-   * @param reserve the address of the reserve to be updated
-   * @param liquidityAdded the amount of liquidity added to the protocol (deposit or repay) in the previous action
-   * @param liquidityTaken the amount of liquidity taken from the protocol (redeem or borrow)
+   * @dev Updates the reserve current stable borrow rate, the current variable borrow rate and the current liquidity rate
+   * @param reserve The address of the reserve to be updated
+   * @param liquidityAdded The amount of liquidity added to the protocol (deposit or repay) in the previous action
+   * @param liquidityTaken The amount of liquidity taken from the protocol (redeem or borrow)
    **/
   function updateInterestRates(
     DataTypes.ReserveData storage reserve,
@@ -265,13 +263,13 @@ library ReserveLogic {
   }
 
   /**
-   * @dev mints part of the repaid interest to the reserve treasury, depending on the reserveFactor for the
+   * @dev Mints part of the repaid interest to the reserve treasury as a function of the reserveFactor for the
    * specific asset.
-   * @param reserve the reserve reserve to be updated
-   * @param scaledVariableDebt the current scaled total variable debt
-   * @param previousVariableBorrowIndex the variable borrow index before the last accumulation of the interest
-   * @param newLiquidityIndex the new liquidity index
-   * @param newVariableBorrowIndex the variable borrow index after the last accumulation of the interest
+   * @param reserve The reserve reserve to be updated
+   * @param scaledVariableDebt The current scaled total variable debt
+   * @param previousVariableBorrowIndex The variable borrow index before the last accumulation of the interest
+   * @param newLiquidityIndex The new liquidity index
+   * @param newVariableBorrowIndex The variable borrow index after the last accumulation of the interest
    **/
   function _mintToTreasury(
     DataTypes.ReserveData storage reserve,
@@ -327,11 +325,11 @@ library ReserveLogic {
   }
 
   /**
-   * @dev updates the reserve indexes and the timestamp of the update
-   * @param reserve the reserve reserve to be updated
-   * @param scaledVariableDebt the scaled variable debt
-   * @param liquidityIndex the last stored liquidity index
-   * @param variableBorrowIndex the last stored variable borrow index
+   * @dev Updates the reserve indexes and the timestamp of the update
+   * @param reserve The reserve reserve to be updated
+   * @param scaledVariableDebt The scaled variable debt
+   * @param liquidityIndex The last stored liquidity index
+   * @param variableBorrowIndex The last stored variable borrow index
    **/
   function _updateIndexes(
     DataTypes.ReserveData storage reserve,
diff --git a/contracts/protocol/libraries/logic/ValidationLogic.sol b/contracts/protocol/libraries/logic/ValidationLogic.sol
index 7df21875..d08e7055 100644
--- a/contracts/protocol/libraries/logic/ValidationLogic.sol
+++ b/contracts/protocol/libraries/logic/ValidationLogic.sol
@@ -19,7 +19,7 @@ import {DataTypes} from '../types/DataTypes.sol';
 /**
  * @title ReserveLogic library
  * @author Aave
- * @notice Implements functions to validate specific action on the protocol.
+ * @notice Implements functions to validate the different actions of the protocol
  */
 library ValidationLogic {
   using ReserveLogic for DataTypes.ReserveData;
@@ -34,9 +34,9 @@ library ValidationLogic {
   uint256 public constant REBALANCE_UP_USAGE_RATIO_THRESHOLD = 0.95 * 1e27; //usage ratio of 95%
 
   /**
-   * @dev validates a deposit.
-   * @param reserve the reserve state on which the user is depositing
-   * @param amount the amount to be deposited
+   * @dev Validates a deposit action
+   * @param reserve The reserve object on which the user is depositing
+   * @param amount The amount to be deposited
    */
   function validateDeposit(DataTypes.ReserveData storage reserve, uint256 amount) external view {
     (bool isActive, bool isFrozen, , ) = reserve.configuration.getFlags();
@@ -47,15 +47,15 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a withdraw action.
-   * @param reserveAddress the address of the reserve
-   * @param amount the amount to be withdrawn
-   * @param userBalance the balance of the user
-   * @param reservesData the reserves state
-   * @param userConfig the user configuration
-   * @param reserves the addresses of the reserves
-   * @param reservesCount the number of reserves
-   * @param oracle the price oracle
+   * @dev Validates a withdraw action
+   * @param reserveAddress The address of the reserve
+   * @param amount The amount to be withdrawn
+   * @param userBalance The balance of the user
+   * @param reservesData The reserves state
+   * @param userConfig The user configuration
+   * @param reserves The addresses of the reserves
+   * @param reservesCount The number of reserves
+   * @param oracle The price oracle
    */
   function validateWithdraw(
     address reserveAddress,
@@ -110,18 +110,18 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a borrow.
-   * @param asset the address of the asset to borrow
-   * @param reserve the reserve state from which the user is borrowing
-   * @param userAddress the address of the user
-   * @param amount the amount to be borrowed
-   * @param amountInETH the amount to be borrowed, in ETH
-   * @param interestRateMode the interest rate mode at which the user is borrowing
-   * @param maxStableLoanPercent the max amount of the liquidity that can be borrowed at stable rate, in percentage
-   * @param reservesData the state of all the reserves
-   * @param userConfig the state of the user for the specific reserve
-   * @param reserves the addresses of all the active reserves
-   * @param oracle the price oracle
+   * @dev Validates a borrow action
+   * @param asset The address of the asset to borrow
+   * @param reserve The reserve state from which the user is borrowing
+   * @param userAddress The address of the user
+   * @param amount The amount to be borrowed
+   * @param amountInETH The amount to be borrowed, in ETH
+   * @param interestRateMode The interest rate mode at which the user is borrowing
+   * @param maxStableLoanPercent The max amount of the liquidity that can be borrowed at stable rate, in percentage
+   * @param reservesData The state of all the reserves
+   * @param userConfig The state of the user for the specific reserve
+   * @param reserves The addresses of all the active reserves
+   * @param oracle The price oracle
    */
 
   function validateBorrow(
@@ -194,8 +194,7 @@ library ValidationLogic {
      * 1. Reserve must be enabled for stable rate borrowing
      * 2. Users cannot borrow from the reserve if their collateral is (mostly) the same currency
      *    they are borrowing, to prevent abuses.
-     * 3. Users will be able to borrow only a relatively small, configurable amount of the total
-     *    liquidity
+     * 3. Users will be able to borrow only a portion of the total available liquidity
      **/
 
     if (vars.rateMode == DataTypes.InterestRateMode.STABLE) {
@@ -221,12 +220,12 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a repay.
-   * @param reserve the reserve state from which the user is repaying
-   * @param amountSent the amount sent for the repayment. Can be an actual value or uint(-1)
-   * @param onBehalfOf the address of the user msg.sender is repaying for
-   * @param stableDebt the borrow balance of the user
-   * @param variableDebt the borrow balance of the user
+   * @dev Validates a repay action
+   * @param reserve The reserve state from which the user is repaying
+   * @param amountSent The amount sent for the repayment. Can be an actual value or uint(-1)
+   * @param onBehalfOf The address of the user msg.sender is repaying for
+   * @param stableDebt The borrow balance of the user
+   * @param variableDebt The borrow balance of the user
    */
   function validateRepay(
     DataTypes.ReserveData storage reserve,
@@ -257,12 +256,12 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a swap of borrow rate mode.
-   * @param reserve the reserve state on which the user is swapping the rate
-   * @param userConfig the user reserves configuration
-   * @param stableDebt the stable debt of the user
-   * @param variableDebt the variable debt of the user
-   * @param currentRateMode the rate mode of the borrow
+   * @dev Validates a swap of borrow rate mode.
+   * @param reserve The reserve state on which the user is swapping the rate
+   * @param userConfig The user reserves configuration
+   * @param stableDebt The stable debt of the user
+   * @param variableDebt The variable debt of the user
+   * @param currentRateMode The rate mode of the borrow
    */
   function validateSwapRateMode(
     DataTypes.ReserveData storage reserve,
@@ -301,12 +300,12 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a stable borrow rate rebalance
-   * @param reserve the reserve state on which the user is getting rebalanced
-   * @param reserveAddress the address of the reserve
-   * @param stableDebtToken the stable debt token instance
-   * @param variableDebtToken the variable debt token instance
-   * @param aTokenAddress the address of the aToken contract
+   * @dev Validates a stable borrow rate rebalance action
+   * @param reserve The reserve state on which the user is getting rebalanced
+   * @param reserveAddress The address of the reserve
+   * @param stableDebtToken The stable debt token instance
+   * @param variableDebtToken The variable debt token instance
+   * @param aTokenAddress The address of the aToken contract
    */
   function validateRebalanceStableBorrowRate(
     DataTypes.ReserveData storage reserve,
@@ -341,13 +340,13 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates the choice of a user of setting (or not) an asset as collateral
-   * @param reserve the state of the reserve that the user is enabling or disabling as collateral
-   * @param reserveAddress the address of the reserve
-   * @param reservesData the data of all the reserves
-   * @param userConfig the state of the user for the specific reserve
-   * @param reserves the addresses of all the active reserves
-   * @param oracle the price oracle
+   * @dev Validates the action of setting an asset as collateral
+   * @param reserve The state of the reserve that the user is enabling or disabling as collateral
+   * @param reserveAddress The address of the reserve
+   * @param reservesData The data of all the reserves
+   * @param userConfig The state of the user for the specific reserve
+   * @param reserves The addresses of all the active reserves
+   * @param oracle The price oracle
    */
   function validateSetUseReserveAsCollateral(
     DataTypes.ReserveData storage reserve,
@@ -380,16 +379,16 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates a flashloan action
-   * @param assets the assets being flashborrowed
-   * @param amounts the amounts for each asset being borrowed
+   * @dev Validates a flashloan action
+   * @param assets The assets being flashborrowed
+   * @param amounts The amounts for each asset being borrowed
    **/
   function validateFlashloan(address[] memory assets, uint256[] memory amounts) internal pure {
     require(assets.length == amounts.length, Errors.VL_INCONSISTENT_FLASHLOAN_PARAMS);
   }
 
   /**
-   * @dev Validates the liquidationCall() action
+   * @dev Validates the liquidation action
    * @param collateralReserve The reserve data of the collateral
    * @param principalReserve The reserve data of the principal
    * @param userConfig The user configuration
@@ -444,12 +443,12 @@ library ValidationLogic {
   }
 
   /**
-   * @dev validates an aToken transfer.
-   * @param from the user from which the aTokens are being transferred
-   * @param reservesData the state of all the reserves
-   * @param userConfig the state of the user for the specific reserve
-   * @param reserves the addresses of all the active reserves
-   * @param oracle the price oracle
+   * @dev Validates an aToken transfer
+   * @param from The user from which the aTokens are being transferred
+   * @param reservesData The state of all the reserves
+   * @param userConfig The state of the user for the specific reserve
+   * @param reserves The addresses of all the active reserves
+   * @param oracle The price oracle
    */
   function validateTransfer(
     address from,
diff --git a/contracts/protocol/libraries/math/MathUtils.sol b/contracts/protocol/libraries/math/MathUtils.sol
index 5ddfeffb..7078a82f 100644
--- a/contracts/protocol/libraries/math/MathUtils.sol
+++ b/contracts/protocol/libraries/math/MathUtils.sol
@@ -12,10 +12,10 @@ library MathUtils {
   uint256 internal constant SECONDS_PER_YEAR = 365 days;
 
   /**
-   * @dev function to calculate the interest using a linear interest rate formula
-   * @param rate the interest rate, in ray
-   * @param lastUpdateTimestamp the timestamp of the last update of the interest
-   * @return the interest rate linearly accumulated during the timeDelta, in ray
+   * @dev Function to calculate the interest accumulated using a linear interest rate formula
+   * @param rate The interest rate, in ray
+   * @param lastUpdateTimestamp The timestamp of the last update of the interest
+   * @return The interest rate linearly accumulated during the timeDelta, in ray
    **/
 
   function calculateLinearInterest(uint256 rate, uint40 lastUpdateTimestamp)
@@ -30,17 +30,17 @@ library MathUtils {
   }
 
   /**
-   * @dev function to calculate the interest using a compounded interest rate formula.
+   * @dev Function to calculate the interest using a compounded interest rate formula
    * To avoid expensive exponentiation, the calculation is performed using a binomial approximation:
    *
    *  (1+x)^n = 1+n*x+[n/2*(n-1)]*x^2+[n/6*(n-1)*(n-2)*x^3...
    *
-   * The approximation slightly underpays liquidity providers, with the advantage of great gas cost reductions.
-   * The whitepaper contains reference to the approximation and a table showing the margin of error per different time periods.
+   * The approximation slightly underpays liquidity providers and undercharges borrowers, with the advantage of great gas cost reductions
+   * The whitepaper contains reference to the approximation and a table showing the margin of error per different time periods
    *
-   * @param rate the interest rate, in ray
-   * @param lastUpdateTimestamp the timestamp of the last update of the interest
-   * @return the interest rate compounded during the timeDelta, in ray
+   * @param rate The interest rate, in ray
+   * @param lastUpdateTimestamp The timestamp of the last update of the interest
+   * @return The interest rate compounded during the timeDelta, in ray
    **/
   function calculateCompoundedInterest(
     uint256 rate,
@@ -70,9 +70,9 @@ library MathUtils {
   }
 
   /**
-   * @dev calculates the compounded interest between the timestamp of the last update and the current block timestamp
-   * @param rate the interest rate (in ray)
-   * @param lastUpdateTimestamp the timestamp from which the interest accumulation needs to be calculated
+   * @dev Calculates the compounded interest between the timestamp of the last update and the current block timestamp
+   * @param rate The interest rate (in ray)
+   * @param lastUpdateTimestamp The timestamp from which the interest accumulation needs to be calculated
    **/
   function calculateCompoundedInterest(uint256 rate, uint40 lastUpdateTimestamp)
     internal
diff --git a/contracts/protocol/libraries/math/PercentageMath.sol b/contracts/protocol/libraries/math/PercentageMath.sol
index 72bb09b6..4fa55d52 100644
--- a/contracts/protocol/libraries/math/PercentageMath.sol
+++ b/contracts/protocol/libraries/math/PercentageMath.sol
@@ -6,7 +6,7 @@ import {Errors} from '../helpers/Errors.sol';
 /**
  * @title PercentageMath library
  * @author Aave
- * @notice Provides functions to calculate percentages.
+ * @notice Provides functions to perform percentage calculations
  * @dev Percentages are defined by default with 2 decimals of precision (100.00). The precision is indicated by PERCENTAGE_FACTOR
  * @dev Operations are rounded half up
  **/
@@ -16,10 +16,10 @@ library PercentageMath {
   uint256 constant HALF_PERCENT = PERCENTAGE_FACTOR / 2;
 
   /**
-   * @dev executes a percentage multiplication
-   * @param value the value of which the percentage needs to be calculated
-   * @param percentage the percentage of the value to be calculated
-   * @return the percentage of value
+   * @dev Executes a percentage multiplication
+   * @param value The value of which the percentage needs to be calculated
+   * @param percentage The percentage of the value to be calculated
+   * @return The percentage of value
    **/
   function percentMul(uint256 value, uint256 percentage) internal pure returns (uint256) {
     if (value == 0 || percentage == 0) {
@@ -35,10 +35,10 @@ library PercentageMath {
   }
 
   /**
-   * @dev executes a percentage division
-   * @param value the value of which the percentage needs to be calculated
-   * @param percentage the percentage of the value to be calculated
-   * @return the value divided the percentage
+   * @dev Executes a percentage division
+   * @param value The value of which the percentage needs to be calculated
+   * @param percentage The percentage of the value to be calculated
+   * @return The value divided the percentage
    **/
   function percentDiv(uint256 value, uint256 percentage) internal pure returns (uint256) {
     require(percentage != 0, Errors.MATH_DIVISION_BY_ZERO);
diff --git a/contracts/protocol/libraries/math/WadRayMath.sol b/contracts/protocol/libraries/math/WadRayMath.sol
index 7fdf8462..f94b38dc 100644
--- a/contracts/protocol/libraries/math/WadRayMath.sol
+++ b/contracts/protocol/libraries/math/WadRayMath.sol
@@ -19,14 +19,14 @@ library WadRayMath {
   uint256 internal constant WAD_RAY_RATIO = 1e9;
 
   /**
-   * @return one ray, 1e27
+   * @return One ray, 1e27
    **/
   function ray() internal pure returns (uint256) {
     return RAY;
   }
 
   /**
-   * @return one wad, 1e18
+   * @return One wad, 1e18
    **/
 
   function wad() internal pure returns (uint256) {
@@ -34,24 +34,24 @@ library WadRayMath {
   }
 
   /**
-   * @return half ray, 1e27/2
+   * @return Half ray, 1e27/2
    **/
   function halfRay() internal pure returns (uint256) {
     return halfRAY;
   }
 
   /**
-   * @return half ray, 1e18/2
+   * @return Half ray, 1e18/2
    **/
   function halfWad() internal pure returns (uint256) {
     return halfWAD;
   }
 
   /**
-   * @dev multiplies two wad, rounding half up to the nearest wad
-   * @param a wad
-   * @param b wad
-   * @return the result of a*b, in wad
+   * @dev Multiplies two wad, rounding half up to the nearest wad
+   * @param a Wad
+   * @param b Wad
+   * @return The result of a*b, in wad
    **/
   function wadMul(uint256 a, uint256 b) internal pure returns (uint256) {
     if (a == 0 || b == 0) {
@@ -64,10 +64,10 @@ library WadRayMath {
   }
 
   /**
-   * @dev divides two wad, rounding half up to the nearest wad
-   * @param a wad
-   * @param b wad
-   * @return the result of a/b, in wad
+   * @dev Divides two wad, rounding half up to the nearest wad
+   * @param a Wad
+   * @param b Wad
+   * @return The result of a/b, in wad
    **/
   function wadDiv(uint256 a, uint256 b) internal pure returns (uint256) {
     require(b != 0, Errors.MATH_DIVISION_BY_ZERO);
@@ -79,10 +79,10 @@ library WadRayMath {
   }
 
   /**
-   * @dev multiplies two ray, rounding half up to the nearest ray
-   * @param a ray
-   * @param b ray
-   * @return the result of a*b, in ray
+   * @dev Multiplies two ray, rounding half up to the nearest ray
+   * @param a Ray
+   * @param b Ray
+   * @return The result of a*b, in ray
    **/
   function rayMul(uint256 a, uint256 b) internal pure returns (uint256) {
     if (a == 0 || b == 0) {
@@ -95,10 +95,10 @@ library WadRayMath {
   }
 
   /**
-   * @dev divides two ray, rounding half up to the nearest ray
-   * @param a ray
-   * @param b ray
-   * @return the result of a/b, in ray
+   * @dev Divides two ray, rounding half up to the nearest ray
+   * @param a Ray
+   * @param b Ray
+   * @return The result of a/b, in ray
    **/
   function rayDiv(uint256 a, uint256 b) internal pure returns (uint256) {
     require(b != 0, Errors.MATH_DIVISION_BY_ZERO);
@@ -110,8 +110,8 @@ library WadRayMath {
   }
 
   /**
-   * @dev casts ray down to wad
-   * @param a ray
+   * @dev Casts ray down to wad
+   * @param a Ray
    * @return a casted to wad, rounded half up to the nearest wad
    **/
   function rayToWad(uint256 a) internal pure returns (uint256) {
@@ -123,8 +123,8 @@ library WadRayMath {
   }
 
   /**
-   * @dev convert wad up to ray
-   * @param a wad
+   * @dev Converts wad up to ray
+   * @param a Wad
    * @return a converted in ray
    **/
   function wadToRay(uint256 a) internal pure returns (uint256) {