From df8a0fe8dc618233f5c297d0d6cf96b98d299b48 Mon Sep 17 00:00:00 2001
From: Francisco Giordano <frangio.1@gmail.com>
Date: Thu, 29 Apr 2021 22:43:39 -0300
Subject: [PATCH] Complete documentation of UUPSUpgradeable

---
 contracts/access/README.adoc              |  2 +-
 contracts/proxy/README.adoc               |  6 ++--
 contracts/proxy/utils/UUPSUpgradeable.sol | 36 ++++++++++++++++++++---
 3 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/contracts/access/README.adoc b/contracts/access/README.adoc
index e59bba0fc..ed8dcc5a5 100644
--- a/contracts/access/README.adoc
+++ b/contracts/access/README.adoc
@@ -1,4 +1,4 @@
-= Access
+= Access Control
 
 [.readme-notice]
 NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access
diff --git a/contracts/proxy/README.adoc b/contracts/proxy/README.adoc
index 8a10bc277..ae278b083 100644
--- a/contracts/proxy/README.adoc
+++ b/contracts/proxy/README.adoc
@@ -58,10 +58,6 @@ By default, the upgrade functionality included in {UUPSUpgradeable} contains a s
 
 {{ERC1967Upgrade}}
 
-== UUPS
-
-{{UUPSUpgradeable}}
-
 == Transparent Proxy
 
 {{TransparentUpgradeableProxy}}
@@ -83,3 +79,5 @@ By default, the upgrade functionality included in {UUPSUpgradeable} contains a s
 == Utils
 
 {{Initializable}}
+
+{{UUPSUpgradeable}}
diff --git a/contracts/proxy/utils/UUPSUpgradeable.sol b/contracts/proxy/utils/UUPSUpgradeable.sol
index 6f9010233..eeb528967 100644
--- a/contracts/proxy/utils/UUPSUpgradeable.sol
+++ b/contracts/proxy/utils/UUPSUpgradeable.sol
@@ -5,24 +5,52 @@ pragma solidity ^0.8.0;
 import "../ERC1967/ERC1967Upgrade.sol";
 
 /**
- * @dev Base contract for building openzeppelin-upgrades compatible implementations for the {ERC1967Proxy}. It includes
- * publicly available upgrade functions that are called by the plugin and by the secure upgrade mechanism to verify
- * continuation of the upgradability.
+ * @dev An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
+ * {ERC1967Proxy}, when this contract is set as the implementation behind such a proxy.
  *
- * The {_authorizeUpgrade} function MUST be overridden to include access restriction to the upgrade mechanism.
+ * A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
+ * reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
+ * `UUPSUpgradeable` with a custom implementation of upgrades.
+ *
+ * The {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism.
  *
  * _Available since v4.1._
  */
 abstract contract UUPSUpgradeable is ERC1967Upgrade {
+    /**
+     * @dev Upgrade the implementation of the proxy to `newImplementation`.
+     *
+     * Calls {_authorizeUpgrade}.
+     *
+     * Emits an {Upgraded} event.
+     */
     function upgradeTo(address newImplementation) external virtual {
         _authorizeUpgrade(newImplementation);
         _upgradeToAndCallSecure(newImplementation, bytes(""), false);
     }
 
+    /**
+     * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
+     * encoded in `data`.
+     *
+     * Calls {_authorizeUpgrade}.
+     *
+     * Emits an {Upgraded} event.
+     */
     function upgradeToAndCall(address newImplementation, bytes memory data) external payable virtual {
         _authorizeUpgrade(newImplementation);
         _upgradeToAndCallSecure(newImplementation, data, true);
     }
 
+    /**
+     * @dev Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
+     * {upgradeTo} and {upgradeToAndCall}.
+     *
+     * Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.
+     *
+     * ```solidity
+     * function _authorizeUpgrade(address) internal override onlyOwner {}
+     * ```
+     */
     function _authorizeUpgrade(address newImplementation) internal virtual;
 }