Add missing docstrings (OpenZeppelin#5168)

Co-authored-by: Ernesto García <[email protected]>
Amxx · Aug 30, 2024 · 58a1147 · 58a1147
1 parent c51cc4d
commit 58a1147
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 7 deletions.
diff --git a/contracts/access/manager/AccessManager.sol b/contracts/access/manager/AccessManager.sol
@@ -97,7 +97,15 @@ contract AccessManager is Context, Multicall, IAccessManager {
         uint32 nonce;
     }
 
+    /**
+     * @dev The identifier of the admin role. Required to perform most configuration operations including
+     * other roles' management and target restrictions.
+     */
     uint64 public constant ADMIN_ROLE = type(uint64).min; // 0
+
+    /**
+     * @dev The identifier of the public role. Automatically granted to all addresses with no delay.
+     */
     uint64 public constant PUBLIC_ROLE = type(uint64).max; // 2**64-1
 
     mapping(address target => TargetConfig mode) private _targets;

diff --git a/contracts/proxy/ERC1967/ERC1967Utils.sol b/contracts/proxy/ERC1967/ERC1967Utils.sol
@@ -9,7 +9,7 @@ import {Address} from "../../utils/Address.sol";
 import {StorageSlot} from "../../utils/StorageSlot.sol";
 
 /**
- * @dev This abstract contract provides getters and event emitting update functions for
+ * @dev This library provides getters and event emitting update functions for
  * https://eips.ethereum.org/EIPS/eip-1967[ERC-1967] slots.
  */
 library ERC1967Utils {

diff --git a/contracts/proxy/transparent/TransparentUpgradeableProxy.sol b/contracts/proxy/transparent/TransparentUpgradeableProxy.sol
@@ -15,7 +15,13 @@ import {ProxyAdmin} from "./ProxyAdmin.sol";
  * include them in the ABI so this interface must be used to interact with it.
  */
 interface ITransparentUpgradeableProxy is IERC1967 {
-    function upgradeToAndCall(address, bytes calldata) external payable;
+    /**
+     * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
+     * encoded in `data`.
+     *
+     * See {UUPSUpgradeable-upgradeToAndCall}
+     */
+    function upgradeToAndCall(address newImplementation, bytes calldata data) external payable;
 }
 
 /**

diff --git a/contracts/utils/Base64.sol b/contracts/utils/Base64.sol
@@ -40,14 +40,17 @@ library Base64 {
 
         // If padding is enabled, the final length should be `bytes` data length divided by 3 rounded up and then
         // multiplied by 4 so that it leaves room for padding the last chunk
-        // - `data.length + 2`  -> Round up
-        // - `/ 3`              -> Number of 3-bytes chunks
+        // - `data.length + 2`  -> Prepare for division rounding up
+        // - `/ 3`              -> Number of 3-bytes chunks (rounded up)
         // - `4 *`              -> 4 characters for each chunk
+        // This is equivalent to: 4 * Math.ceil(data.length / 3)
+        //
         // If padding is disabled, the final length should be `bytes` data length multiplied by 4/3 rounded up as
         // opposed to when padding is required to fill the last chunk.
-        // - `4 *`              -> 4 characters for each chunk
-        // - `data.length + 2`  -> Round up
-        // - `/ 3`              -> Number of 3-bytes chunks
+        // - `4 * data.length`  -> 4 characters for each chunk
+        // - ` + 2`             -> Prepare for division rounding up
+        // - `/ 3`              -> Number of 3-bytes chunks (rounded up)
+        // This is equivalent to: Math.ceil((4 * data.length) / 3)
         uint256 resultLength = withPadding ? 4 * ((data.length + 2) / 3) : (4 * data.length + 2) / 3;
 
         string memory result = new string(resultLength);