Merge branch 'feat/153-improve-docs' into 'master'

- First iteration of documentation improvement of contracts

See merge request aave-tech/protocol-v2!179

Author: The-3D

contracts/deployments/ATokensAndRatesHelper.sol

@@ -12,7 +12,7 @@ import {
   DefaultReserveInterestRateStrategy
 } from '../protocol/lendingpool/DefaultReserveInterestRateStrategy.sol';
 import {Ownable} from '../dependencies/openzeppelin/contracts/Ownable.sol';
-import {StringLib} from '../protocol/libraries/helpers/StringLib.sol';
+import {StringLib} from './StringLib.sol';
 
 contract ATokensAndRatesHelper is Ownable {
   address payable private pool;
@@ -108,16 +108,16 @@ contract ATokensAndRatesHelper is Ownable {
     }
   }
 
-  function enableBorrowingOnReserves(address[] calldata tokens, bool[] calldata stableBorrows)
+  function enableBorrowingOnReserves(address[] calldata tokens, bool[] calldata stableBorrowingEnabled)
     external
     onlyOwner
   {
-    require(stableBorrows.length == tokens.length);
+    require(stableBorrowingEnabled.length == tokens.length);
 
     for (uint256 i = 0; i < tokens.length; i++) {
       LendingPoolConfigurator(poolConfigurator).enableBorrowingOnReserve(
         tokens[i],
-        stableBorrows[i]
+        stableBorrowingEnabled[i]
       );
     }
   }

contracts/deployments/StableAndVariableTokensHelper.sol

@@ -6,7 +6,7 @@ import {StableDebtToken} from '../protocol/tokenization/StableDebtToken.sol';
 import {VariableDebtToken} from '../protocol/tokenization/VariableDebtToken.sol';
 import {LendingRateOracle} from '../mocks/oracle/LendingRateOracle.sol';
 import {Ownable} from '../dependencies/openzeppelin/contracts/Ownable.sol';
-import {StringLib} from '../protocol/libraries/helpers/StringLib.sol';
+import {StringLib} from './StringLib.sol';
 
 contract StableAndVariableTokensHelper is Ownable {
   address payable private pool;

contracts/protocol/libraries/helpers/StringLib.sol renamed to contracts/deployments/StringLib.sol

@@ -2,31 +2,26 @@
 pragma solidity 0.6.12;
 
 /**
-@title ILendingPoolAddressesProvider interface
-@notice provides the interface to fetch the Aave protocol address
- */
-
+ * @title LendingPoolAddressesProvider contract
+ * @dev Main registry of addresses part of or connected to the protocol, including permissioned roles
+ * - Acting also as factory of proxies and admin of those, so with right to change its implementations
+ * - Owned by the Aave Governance
+ * @author Aave
+ **/
 interface ILendingPoolAddressesProvider {
   event LendingPoolUpdated(address indexed newAddress);
   event ConfigurationAdminUpdated(address indexed newAddress);
   event EmergencyAdminUpdated(address indexed newAddress);
   event LendingPoolConfiguratorUpdated(address indexed newAddress);
   event LendingPoolCollateralManagerUpdated(address indexed newAddress);
-  event EthereumAddressUpdated(address indexed newAddress);
   event PriceOracleUpdated(address indexed newAddress);
   event LendingRateOracleUpdated(address indexed newAddress);
   event ProxyCreated(bytes32 id, address indexed newAddress);
   event AddressSet(bytes32 id, address indexed newAddress, bool hasProxy);
 
-  function setAddress(
-    bytes32 id,
-    address newAddress
-  ) external;
+  function setAddress(bytes32 id, address newAddress) external;
 
-  function setAddressAsProxy(
-    bytes32 id,
-    address impl
-  ) external;
+  function setAddressAsProxy(bytes32 id, address impl) external;
 
   function getAddress(bytes32 id) external view returns (address);
 

contracts/interfaces/ILendingPool.sol

@@ -2,17 +2,19 @@
 pragma solidity 0.6.12;
 
 /**
- * @title ILendingPoolAddressesProvider interface
- * @notice provides the interface to fetch the LendingPoolCore address
+ * @title LendingPoolAddressesProviderRegistry contract
+ * @dev Main registry of LendingPoolAddressesProvider of multiple Aave protocol's markets
+ * - Used for indexing purposes of Aave protocol's markets
+ * - The id assigned to a LendingPoolAddressesProvider refers to the market it is connected with,
+ *   for example with `0` for the Aave main market and `1` for the next created
+ * @author Aave
  **/
 interface ILendingPoolAddressesProviderRegistry {
   event AddressesProviderRegistered(address indexed newAddress);
   event AddressesProviderUnregistered(address indexed newAddress);
 
   function getAddressesProvidersList() external view returns (address[] memory);
 
-  function isAddressesProviderRegistered(address provider) external view returns (uint256);
-
   function getAddressesProviderIdByAddress(address addressesProvider)
     external
     view

contracts/interfaces/ILendingPoolAddressesProvider.sol

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: agpl-3.0
+pragma solidity 0.6.12;
+
+/**
+ * @title ILendingPoolCollateralManager interface
+ * @author Aave
+ * @notice Defines the actions involving management of collateral in the protocol.
+ **/
+interface ILendingPoolCollateralManager {
+  /**
+   * @dev emitted when a borrower is liquidated
+   * @param collateral the address of the collateral being liquidated
+   * @param principal the address of the reserve
+   * @param user the address of the user being liquidated
+   * @param debtToCover the total amount liquidated
+   * @param liquidatedCollateralAmount the amount of collateral being liquidated
+   * @param liquidator the address of the liquidator
+   * @param receiveAToken true if the liquidator wants to receive aTokens, false otherwise
+   **/
+  event LiquidationCall(
+    address indexed collateral,
+    address indexed principal,
+    address indexed user,
+    uint256 debtToCover,
+    uint256 liquidatedCollateralAmount,
+    address liquidator,
+    bool receiveAToken
+  );
+
+  /**
+   * @dev emitted when a user disables a reserve as collateral
+   * @param reserve the address of the reserve
+   * @param user the address of the user
+   **/
+  event ReserveUsedAsCollateralDisabled(address indexed reserve, address indexed user);
+
+  /**
+   * @dev users can invoke this function to liquidate an undercollateralized position.
+   * @param collateral the address of the collateral to liquidated
+   * @param principal the address of the principal reserve
+   * @param user the address of the borrower
+   * @param debtToCover the amount of principal that the liquidator wants to repay
+   * @param receiveAToken true if the liquidators wants to receive the aTokens, false if
+   * he wants to receive the underlying asset directly
+   **/
+  function liquidationCall(
+    address collateral,
+    address principal,
+    address user,
+    uint256 debtToCover,
+    bool receiveAToken
+  ) external virtual returns (uint256, string memory);
+}

contracts/interfaces/ILendingPoolAddressesProviderRegistry.sol

@@ -2,26 +2,15 @@
 pragma solidity 0.6.12;
 
 /**
-@title IReserveInterestRateStrategyInterface interface
-@notice Interface for the calculation of the interest rates.
-*/
-
+ * @title IReserveInterestRateStrategyInterface interface
+ * @dev Interface for the calculation of the interest rates
+ * @author Aave
+ */
 interface IReserveInterestRateStrategy {
-  /**
-   * @dev returns the base variable borrow rate, in rays
-   */
   function baseVariableBorrowRate() external view returns (uint256);
 
-  /**
-   * @dev returns the maximum variable borrow rate
-   */
   function getMaxVariableBorrowRate() external view returns (uint256);
 
-  /**
-   * @dev calculates the liquidity, stable, and variable rates depending on the current utilization rate
-   *      and the base parameters
-   *
-   */
   function calculateInterestRates(
     address reserve,
     uint256 utilizationRate,

contracts/interfaces/ILendingPoolCollateralManager.sol

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: agpl-3.0
 pragma solidity >=0.6.2;
 
 interface IUniswapV2Router01 {

contracts/interfaces/IReserveInterestRateStrategy.sol

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: agpl-3.0
 pragma solidity >=0.6.2;
 
 import './IUniswapV2Router01.sol';