- Improved docs of LendingPoolAddressesProvider

contracts/configuration/LendingPoolAddressesProvider.sol

@@ -11,11 +11,11 @@ import {ILendingPoolAddressesProvider} from '../interfaces/ILendingPoolAddresses
 
 /**
  * @title LendingPoolAddressesProvider contract
- * @notice Is the main registry of the protocol. All the different components of the protocol are accessible
+ * @dev Main registry of addresses part or connected to the protocol.
- * through the addresses provider.
+ * - Acting also as factory of proxies and admin of those, so with right to change it's implementations
+ * - Owned by the Aave Governance
  * @author Aave
  **/
-
 contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider {
   mapping(bytes32 => address) private _addresses;
 
@@ -28,28 +28,30 @@ 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
+   * @param implementationAddress The address of the new implementation
-   * address(0) if we don't want a proxy covering
    */
-  function setAddressAsProxy(
+  function setAddressAsProxy(bytes32 id, address implementationAddress)
-    bytes32 id,
+    external
-    address implementationAddress
+    override
-  ) external override onlyOwner {
+    onlyOwner
+  {
     _updateImpl(id, implementationAddress);
     emit AddressSet(id, implementationAddress, true);
   }
 
   /**
    * @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(
+  function setAddress(bytes32 id, address newAddress) external override onlyOwner {
-    bytes32 id,
-    address newAddress
-  ) external override onlyOwner {
     _addresses[id] = newAddress;
     emit AddressSet(id, newAddress, false);
   }
@@ -63,16 +65,17 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev returns the address of the LendingPool proxy
+   * @dev Returns the address of the LendingPool proxy
-   * @return the lending pool proxy address
+   * @return The LendingPool proxy address
    **/
   function getLendingPool() external override view returns (address) {
     return getAddress(LENDING_POOL);
   }
 
   /**
-   * @dev updates the implementation of the lending pool
+   * @dev Updates the implementation of the LendingPool, or creates the proxy
-   * @param pool the new lending pool implementation
+   * 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);
@@ -80,16 +83,17 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev returns the address of the LendingPoolConfigurator proxy
+   * @dev Returns the address of the LendingPoolConfigurator proxy
-   * @return the lending pool configurator proxy address
+   * @return The LendingPoolConfigurator proxy address
    **/
   function getLendingPoolConfigurator() external override view returns (address) {
     return getAddress(LENDING_POOL_CONFIGURATOR);
   }
 
   /**
-   * @dev updates the implementation of the lending pool configurator
+   * @dev Updates the implementation of the LendingPoolConfigurator, or creates the proxy
-   * @param configurator the new lending pool configurator implementation
+   * 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);
@@ -97,10 +101,10 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @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.
+   * the addresses are changed directly
-   * @return the address of the Lending pool collateral manager
+   * @return The address of the LendingPoolCollateralManager
    **/
 
   function getLendingPoolCollateralManager() external override view returns (address) {
@@ -108,8 +112,8 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev updates the address of the Lending pool collateral manager
+   * @dev Updates the address of the LendingPoolCollateralManager
-   * @param manager the new lending pool collateral manager address
+   * @param manager The new LendingPoolCollateralManager address
    **/
   function setLendingPoolCollateralManager(address manager) external override onlyOwner {
     _addresses[LENDING_POOL_COLLATERAL_MANAGER] = manager;
@@ -117,8 +121,8 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev the functions below are storing specific addresses that are outside the context of the protocol
+   * @dev The functions below are getters/setters of addresses that are outside the context
-   * hence the upgradable proxy pattern is not used
+   * of the protocol hence the upgradable proxy pattern is not used
    **/
 
   function getPoolAdmin() external override view returns (address) {
@@ -158,9 +162,13 @@ contract LendingPoolAddressesProvider is Ownable, ILendingPoolAddressesProvider
   }
 
   /**
-   * @dev internal function to update the implementation of a specific component of the protocol
+   * @dev Internal function to update the implementation of a specific proxied component of the protocol
-   * @param id the id of the contract to be updated
+   * - If there is no proxy registered in the given `id`, it creates the proxy setting `newAdress`
-   * @param newAddress the address of the new implementation
+   *   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]);