Complete documentation of UUPSUpgradeable

contracts/access/README.adoc

-= Access
+= Access Control
 
 [.readme-notice]
 NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/access

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}}

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;
 }