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

- First iteration of documentation improvement of contracts

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

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/interfaces/ILendingPoolAddressesProvider.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/ILendingPoolAddressesProviderRegistry.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/ILendingPoolCollateralManager.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/IReserveInterestRateStrategy.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/misc/interfaces/IUniswapV2Router01.sol

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

contracts/misc/interfaces/IUniswapV2Router02.sol

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

contracts/mocks/tokens/WETH9Mocked.sol

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: agpl-3.0
 pragma solidity >=0.4.22 <=0.6.12;
 
 import {WETH9} from '../dependencies/weth/WETH9.sol';

contracts/protocol/configuration/LendingPoolAddressesProvider.sol

@@ -11,11 +11,11 @@ import {ILendingPoolAddressesProvider} from '../../interfaces/ILendingPoolAddres
 
 /**
  * @title LendingPoolAddressesProvider contract
- * @notice Is the main registry of the protocol. All the different components of the protocol are accessible
- * through the addresses provider.
+ * @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
  **/
-
 contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider {
   mapping(bytes32 => address) private _addresses;
 
@@ -28,10 +28,13 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   bytes32 private constant LENDING_RATE_ORACLE = 'LENDING_RATE_ORACLE';
 
   /**
-   * @dev Sets an address for an id by updating a proxy implementation
+   * @dev General function to update the implementation of a proxy registered with
+   * certain `id`. If there is no proxy registered, it will instantiate one and
+   * set as implementation the `implementationAddress`
+   * IMPORTANT Use this function carefully, only for ids that don't have an explicit
+   * setter function, in order to avoid unexpected consequences
    * @param id The id
-   * @param implementationAddress The address of the implementation if we want it covered by a proxy
-   * address(0) if we don't want a proxy covering
+   * @param implementationAddress The address of the new implementation
    */
   function setAddressAsProxy(bytes32 id, address implementationAddress)
     external
@@ -44,8 +47,9 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
 
   /**
    * @dev Sets an address for an id replacing the address saved in the addresses map
+   * IMPORTANT Use this function carefully, as it will do a hard replacement
    * @param id The id
-   * @param newAddress The address to set, pass address(0) if a proxy is needed
+   * @param newAddress The address to set
    */
   function setAddress(bytes32 id, address newAddress) external override onlyOwner {
     _addresses[id] = newAddress;
@@ -61,62 +65,64 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev returns the address of the LendingPool proxy
-   * @return the lending pool proxy address
+   * @dev Returns the address of the LendingPool proxy
+   * @return The LendingPool proxy address
    **/
   function getLendingPool() external view override returns (address) {
     return getAddress(LENDING_POOL);
   }
 
   /**
-   * @dev updates the implementation of the lending pool
-   * @param pool the new lending pool implementation
+   * @dev Updates the implementation of the LendingPool, or creates the proxy
+   * setting the new `pool` implementation on the first time calling it
+   * @param pool The new LendingPool implementation
    **/
   function setLendingPoolImpl(address pool) external override onlyOwner {
     _updateImpl(LENDING_POOL, pool);
     emit LendingPoolUpdated(pool);
   }
 
   /**
-   * @dev returns the address of the LendingPoolConfigurator proxy
-   * @return the lending pool configurator proxy address
+   * @dev Returns the address of the LendingPoolConfigurator proxy
+   * @return The LendingPoolConfigurator proxy address
    **/
   function getLendingPoolConfigurator() external view override returns (address) {
     return getAddress(LENDING_POOL_CONFIGURATOR);
   }
 
   /**
-   * @dev updates the implementation of the lending pool configurator
-   * @param configurator the new lending pool configurator implementation
+   * @dev Updates the implementation of the LendingPoolConfigurator, or creates the proxy
+   * setting the new `configurator` implementation on the first time calling it
+   * @param configurator The new LendingPoolConfigurator implementation
    **/
   function setLendingPoolConfiguratorImpl(address configurator) external override onlyOwner {
     _updateImpl(LENDING_POOL_CONFIGURATOR, configurator);
     emit LendingPoolConfiguratorUpdated(configurator);
   }
 
   /**
-   * @dev returns the address of the LendingPoolCollateralManager. Since the manager is used
+   * @dev Returns the address of the LendingPoolCollateralManager. Since the manager is used
    * through delegateCall within the LendingPool contract, the proxy contract pattern does not work properly hence
-   * the addresses are changed directly.
-   * @return the address of the Lending pool collateral manager
+   * the addresses are changed directly
+   * @return The address of the LendingPoolCollateralManager
    **/
 
   function getLendingPoolCollateralManager() external view override returns (address) {
     return getAddress(LENDING_POOL_COLLATERAL_MANAGER);
   }
 
   /**
-   * @dev updates the address of the Lending pool collateral manager
-   * @param manager the new lending pool collateral manager address
+   * @dev Updates the address of the LendingPoolCollateralManager
+   * @param manager The new LendingPoolCollateralManager address
    **/
   function setLendingPoolCollateralManager(address manager) external override onlyOwner {
     _addresses[LENDING_POOL_COLLATERAL_MANAGER] = manager;
     emit LendingPoolCollateralManagerUpdated(manager);
   }
 
   /**
-   * @dev the functions below are storing specific addresses that are outside the context of the protocol
-   * hence the upgradable proxy pattern is not used
+   * @dev The functions below are getters/setters of addresses that are outside the context
+   * of the protocol hence the upgradable proxy pattern is not used
    **/
 
   function getPoolAdmin() external view override returns (address) {
@@ -156,9 +162,13 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev internal function to update the implementation of a specific component of the protocol
-   * @param id the id of the contract to be updated
-   * @param newAddress the address of the new implementation
+   * @dev Internal function to update the implementation of a specific proxied component of the protocol
+   * - If there is no proxy registered in the given `id`, it creates the proxy setting `newAdress`
+   *   as implementation and calls the initialize() function on the proxy
+   * - If there is already a proxy registered, it just updates the implementation to `newAddress` and
+   *   calls the initialize() function via upgradeToAndCall() in the proxy
+   * @param id The id of the proxy to be updated
+   * @param newAddress The address of the new implementation
    **/
   function _updateImpl(bytes32 id, address newAddress) internal {
     address payable proxyAddress = payable(_addresses[id]);