thirdweb-dev · nkrishang · Jul 29, 2022 · Jul 14, 2022 · Jul 14, 2022 · Jul 14, 2022
diff --git a/contracts/extension/BatchMintMetadata.sol b/contracts/extension/BatchMintMetadata.sol
@@ -2,9 +2,10 @@
 pragma solidity ^0.8.0;
 
 /**
- *  The `BatchMintMetadata` is a contract extension for any base NFT contract. It lets the smart contract
- *  using this extension set metadata for `n` number of NFTs all at once. This is enabled by storing a single
- *  base URI for a batch of `n` NFTs, where the metadata for each NFT in a relevant batch is `baseURI/tokenId`.
+ *  @title   Batch-mint Metadata
+ *  @notice  The `BatchMintMetadata` is a contract extension for any base NFT contract. It lets the smart contract
+ *           using this extension set metadata for `n` number of NFTs all at once. This is enabled by storing a single
+ *           base URI for a batch of `n` NFTs, where the metadata for each NFT in a relevant batch is `baseURI/tokenId`.
  */
 
 contract BatchMintMetadata {
@@ -14,12 +15,20 @@ contract BatchMintMetadata {
     /// @dev Mapping from id of a batch of tokens => to base URI for the respective batch of tokens.
     mapping(uint256 => string) private baseURI;
 
-    /// @dev Returns the number of batches of tokens having the same baseURI.
+    /**
+     *  @notice         Returns the count of batches of NFTs.
+     *  @dev            Each batch of tokens has an in ID and an associated `baseURI`.
+     *                  See {batchIds}.
+     */
     function getBaseURICount() public view returns (uint256) {
         return batchIds.length;
     }
 
-    /// @dev Returns the id for the batch of tokens the given tokenId belongs to.
+    /**
+     *  @notice         Returns the ID for the batch of tokens the given tokenId belongs to.
+     *  @dev            See {getBaseURICount}.
+     *  @param _index   ID of a token.
+     */
     function getBatchIdAtIndex(uint256 _index) public view returns (uint256) {
         if (_index >= getBaseURICount()) {
             revert("Invalid index");

diff --git a/contracts/extension/ContractMetadata.sol b/contracts/extension/ContractMetadata.sol
@@ -4,17 +4,24 @@ pragma solidity ^0.8.0;
 import "./interface/IContractMetadata.sol";
 
 /**
- *  Thirdweb's `ContractMetadata` is a contract extension for any base contracts. It lets you set a metadata URI
- *  for you contract.
- *
- *  Additionally, `ContractMetadata` is necessary for NFT contracts that want royalties to get distributed on OpenSea.
+ *  @title   Contract Metadata
+ *  @notice  Thirdweb's `ContractMetadata` is a contract extension for any base contracts. It lets you set a metadata URI
+ *           for you contract.
+ *           Additionally, `ContractMetadata` is necessary for NFT contracts that want royalties to get distributed on OpenSea.
  */
 
 abstract contract ContractMetadata is IContractMetadata {
-    /// @dev Contract level metadata.
+    /// @notice Returns the contract metadata URI.
     string public override contractURI;
 
-    /// @dev Lets a contract admin set the URI for contract-level metadata.
+    /**
+     *  @notice         Lets a contract admin set the URI for contract-level metadata.
+     *  @dev            Caller should be authorized to setup contractURI, e.g. contract admin.
+     *                  See {_canSetContractURI}.
+     *                  Emits {ContractURIUpdated Event}.
+     *
+     *  @param _uri     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     */
     function setContractURI(string memory _uri) external override {
         if (!_canSetContractURI()) {
             revert("Not authorized");

diff --git a/contracts/extension/DelayedReveal.sol b/contracts/extension/DelayedReveal.sol
@@ -4,8 +4,9 @@ pragma solidity ^0.8.0;
 import "./interface/IDelayedReveal.sol";
 
 /**
- *  Thirdweb's `DelayedReveal` is a contract extension for base NFT contracts. It lets you create batches of
- *  'delayed-reveal' NFTs. You can learn more about the usage of delayed reveal NFTs here - https://blog.thirdweb.com/delayed-reveal-nfts
+ *  @title   Delayed Reveal
+ *  @notice  Thirdweb's `DelayedReveal` is a contract extension for base NFT contracts. It lets you create batches of
+ *           'delayed-reveal' NFTs. You can learn more about the usage of delayed reveal NFTs here - https://blog.thirdweb.com/delayed-reveal-nfts
  */
 
 abstract contract DelayedReveal is IDelayedReveal {
@@ -17,7 +18,17 @@ abstract contract DelayedReveal is IDelayedReveal {
         encryptedBaseURI[_batchId] = _encryptedBaseURI;
     }
 
-    /// @dev Returns the decrypted i.e. revealed URI for a batch of tokens.
+    /**
+     *  @notice             Returns revealed URI for a batch of NFTs.
+     *  @dev                Reveal encrypted base URI for `_batchId` with caller/admin's `_key` used for encryption.
+     *                      Reverts if there's no encrypted URI for `_batchId`.
+     *                      See {encryptDecrypt}.
+     *
+     *  @param _batchId     ID of the batch for which URI is being revealed.
+     *  @param _key         Secure key used by caller/admin for encryption of baseURI.
+     *
+     *  @return revealedURI Decrypted base URI.
+     */
     function getRevealURI(uint256 _batchId, bytes calldata _key) public view returns (string memory revealedURI) {
         bytes memory encryptedURI = encryptedBaseURI[_batchId];
         if (encryptedURI.length == 0) {
@@ -27,7 +38,16 @@ abstract contract DelayedReveal is IDelayedReveal {
         revealedURI = string(encryptDecrypt(encryptedURI, _key));
     }
 
-    /// @dev See: https://ethereum.stackexchange.com/questions/69825/decrypt-message-on-chain
+    /**
+     *  @notice         Encrypt/decrypt data on chain.
+     *  @dev            Encrypt/decrypt given `data` with `key`. Uses inline assembly.
+     *                  See: https://ethereum.stackexchange.com/questions/69825/decrypt-message-on-chain
+     *
+     *  @param data     Bytes of data to encrypt/decrypt.
+     *  @param key      Secure key used by caller for encryption/decryption.
+     *
+     *  @return result  Output after encryption/decryption of given data.
+     */
     function encryptDecrypt(bytes memory data, bytes calldata key) public pure override returns (bytes memory result) {
         // Store data length on stack for later use
         uint256 length = data.length;
@@ -63,7 +83,11 @@ abstract contract DelayedReveal is IDelayedReveal {
         }
     }
 
-    /// @dev Returns whether the relvant batch of NFTs is subject to a delayed reveal.
+    /**
+     *  @notice         Returns whether the relvant batch of NFTs is subject to a delayed reveal.
+     *  @dev            Returns `true` if `_batchId`'s base URI is encrypted.
+     *  @param _batchId ID of a batch of NFTs.
+     */
     function isEncryptedBatch(uint256 _batchId) public view returns (bool) {
         return encryptedBaseURI[_batchId].length > 0;
     }

diff --git a/contracts/extension/Multicall.sol b/contracts/extension/Multicall.sol
@@ -13,7 +13,11 @@ import "./interface/IMulticall.sol";
  */
 contract Multicall is IMulticall {
     /**
-     * @dev Receives and executes a batch of function calls on this contract.
+     *  @notice Receives and executes a batch of function calls on this contract.
+     *  @dev Receives and executes a batch of function calls on this contract.
+     *
+     *  @param data The bytes data that makes up the batch of function calls to execute.
+     *  @return results The bytes data that makes up the result of the batch of function calls executed.
      */
     function multicall(bytes[] calldata data) external virtual override returns (bytes[] memory results) {
         results = new bytes[](data.length);

diff --git a/contracts/extension/Ownable.sol b/contracts/extension/Ownable.sol
@@ -4,9 +4,10 @@ pragma solidity ^0.8.0;
 import "./interface/IOwnable.sol";
 
 /**
- *  Thirdweb's `Ownable` is a contract extension to be used with any base contract. It exposes functions for setting and reading
- *  who the 'owner' of the inheriting smart contract is, and lets the inheriting contract perform conditional logic that uses
- *  information about who the contract's owner is.
+ *  @title   Ownable
+ *  @notice  Thirdweb's `Ownable` is a contract extension to be used with any base contract. It exposes functions for setting and reading
+ *           who the 'owner' of the inheriting smart contract is, and lets the inheriting contract perform conditional logic that uses
+ *           information about who the contract's owner is.
  */
 
 abstract contract Ownable is IOwnable {
@@ -21,12 +22,17 @@ abstract contract Ownable is IOwnable {
         _;
     }
 
-    /// @dev Returns the owner of the contract.
+    /**
+     *  @notice Returns the owner of the contract.
+     */
     function owner() public view override returns (address) {
         return _owner;
     }
 
-    /// @dev Lets a contract admin set a new owner for the contract. The new owner must be a contract admin.
+    /**
+     *  @notice Lets an authorized wallet set a new owner for the contract.
+     *  @param _newOwner The address to set as the new owner of the contract.
+     */
     function setOwner(address _newOwner) external override {
         if (!_canSetOwner()) {
             revert("Not authorized");

diff --git a/contracts/extension/Permissions.sol b/contracts/extension/Permissions.sol
@@ -4,21 +4,51 @@ pragma solidity ^0.8.0;
 import "./interface/IPermissions.sol";
 import "../lib/TWStrings.sol";
 
+/**
+ *  @title   Permissions
+ *  @dev     This contracts provides extending-contracts with role-based access control mechanisms
+ */
 contract Permissions is IPermissions {
+    /// @dev Map from keccak256 hash of a role => a map from address => whether address has role.
     mapping(bytes32 => mapping(address => bool)) private _hasRole;
+
+    /// @dev Map from keccak256 hash of a role to role admin. See {getRoleAdmin}.
     mapping(bytes32 => bytes32) private _getRoleAdmin;
 
+    /// @dev Default admin role for all roles. Only accounts with this role can grant/revoke other roles.
     bytes32 public constant DEFAULT_ADMIN_ROLE = 0x00;
 
+    /// @dev Modifier that checks if an account has the specified role; reverts otherwise.
     modifier onlyRole(bytes32 role) {
         _checkRole(role, msg.sender);
         _;
     }
 
+    /**
+     *  @notice         Checks whether an account has a particular role.
+     *  @dev            Returns `true` if `account` has been granted `role`.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     *  @param account  Address of the account for which the role is being checked.
+     */
     function hasRole(bytes32 role, address account) public view override returns (bool) {
         return _hasRole[role][account];
     }
 
+    /**
+     *  @notice         Checks whether an account has a particular role;
+     *                  role restrictions can be swtiched on and off.
+     *
+     *  @dev            Returns `true` if `account` has been granted `role`.
+     *                  Role restrictions can be swtiched on and off:
+     *                      - If address(0) has ROLE, then the ROLE restrictions
+     *                        don't apply.
+     *                      - If address(0) does not have ROLE, then the ROLE
+     *                        restrictions will apply.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     *  @param account  Address of the account for which the role is being checked.
+     */
     function hasRoleWithSwitch(bytes32 role, address account) public view returns (bool) {
         if (!_hasRole[role][address(0)]) {
             return _hasRole[role][account];
@@ -27,10 +57,25 @@ contract Permissions is IPermissions {
         return true;
     }
 
+    /**
+     *  @notice         Returns the admin role that controls the specified role.
+     *  @dev            See {grantRole} and {revokeRole}.
+     *                  To change a role's admin, use {_setRoleAdmin}.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     */
     function getRoleAdmin(bytes32 role) external view override returns (bytes32) {
         return _getRoleAdmin[role];
     }
 
+    /**
+     *  @notice         Grants a role to an account, if not previously granted.
+     *  @dev            Caller must have admin role for the `role`.
+     *                  Emits {RoleGranted Event}.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     *  @param account  Address of the account to which the role is being granted.
+     */
     function grantRole(bytes32 role, address account) public virtual override {
         _checkRole(_getRoleAdmin[role], msg.sender);
         if (_hasRole[role][account]) {
@@ -39,35 +84,55 @@ contract Permissions is IPermissions {
         _setupRole(role, account);
     }
 
+    /**
+     *  @notice         Revokes role from an account.
+     *  @dev            Caller must have admin role for the `role`.
+     *                  Emits {RoleRevoked Event}.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     *  @param account  Address of the account from which the role is being revoked.
+     */
     function revokeRole(bytes32 role, address account) public virtual override {
         _checkRole(_getRoleAdmin[role], msg.sender);
         _revokeRole(role, account);
     }
 
+    /**
+     *  @notice         Revokes role from the account.
+     *  @dev            Caller must have the `role`, with caller being the same as `account`.
+     *                  Emits {RoleRevoked Event}.
+     *
+     *  @param role     keccak256 hash of the role. e.g. keccak256("TRANSFER_ROLE")
+     *  @param account  Address of the account from which the role is being revoked.
+     */
     function renounceRole(bytes32 role, address account) public virtual override {
         if (msg.sender != account) {
             revert("Can only renounce for self");
         }
         _revokeRole(role, account);
     }
 
+    /// @dev Sets `adminRole` as `role`'s admin role.
     function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal virtual {
         bytes32 previousAdminRole = _getRoleAdmin[role];
         _getRoleAdmin[role] = adminRole;
         emit RoleAdminChanged(role, previousAdminRole, adminRole);
     }
 
+    /// @dev Sets up `role` for `account`
     function _setupRole(bytes32 role, address account) internal virtual {
         _hasRole[role][account] = true;
         emit RoleGranted(role, account, msg.sender);
     }
 
+    /// @dev Revokes `role` from `account`
     function _revokeRole(bytes32 role, address account) internal virtual {
         _checkRole(role, account);
         delete _hasRole[role][account];
         emit RoleRevoked(role, account, msg.sender);
     }
 
+    /// @dev Checks `role` for `account`. Reverts with a message including the required role.
     function _checkRole(bytes32 role, address account) internal view virtual {
         if (!_hasRole[role][account]) {
             revert(
@@ -83,6 +148,7 @@ contract Permissions is IPermissions {
         }
     }
 
+    /// @dev Checks `role` for `account`. Reverts with a message including the required role.
     function _checkRoleWithSwitch(bytes32 role, address account) internal view virtual {
         if (!hasRoleWithSwitch(role, account)) {
             revert(