From c4be4d16e8f714c483309dbd53a27b8e7b26036b Mon Sep 17 00:00:00 2001 From: GuiCz <115c7a5fac@pm.me> Date: Tue, 21 Apr 2020 20:00:48 +0200 Subject: [PATCH] ERC721 documentation (#2164) * Add documentation to the IERC721 contract * Add documentation to the IERC721Metadata contract * Add documentation to the IERC721Enumerable contract * Improves IERC721 documentation * Improves IERC721Metadata documentation * Improves IERC721Enumerable documentation * Fixes documentations issues in IERC721 * Improves ERC721 interfaces documentation --- contracts/token/ERC721/IERC721.sol | 99 +++++++++++++++++--- contracts/token/ERC721/IERC721Enumerable.sol | 13 +++ contracts/token/ERC721/IERC721Metadata.sol | 12 +++ 3 files changed, 110 insertions(+), 14 deletions(-) diff --git a/contracts/token/ERC721/IERC721.sol b/contracts/token/ERC721/IERC721.sol index 88a1cd2c8..c7c0d26dd 100644 --- a/contracts/token/ERC721/IERC721.sol +++ b/contracts/token/ERC721/IERC721.sol @@ -6,48 +6,119 @@ import "../../introspection/IERC165.sol"; * @dev Required interface of an ERC721 compliant contract. */ interface IERC721 is IERC165 { + /** + * @dev Emitted when `tokenId` token is transfered from `from` to `to`. + */ event Transfer(address indexed from, address indexed to, uint256 indexed tokenId); + + /** + * @dev Emitted when `owner` enables `approved` to manage the `tokenId` token. + */ event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId); + + /** + * @dev Emitted when `owner` enables or disables (`approved`) `operator` to manage all of its assets. + */ event ApprovalForAll(address indexed owner, address indexed operator, bool approved); /** - * @dev Returns the number of NFTs in ``owner``'s account. + * @dev Returns the number of tokens in ``owner``'s account. */ function balanceOf(address owner) external view returns (uint256 balance); /** - * @dev Returns the owner of the NFT specified by `tokenId`. + * @dev Returns the owner of the `tokenId` token. + * + * Requirements: + * + * - `tokenId` must exist. */ function ownerOf(uint256 tokenId) external view returns (address owner); /** - * @dev Transfers a specific NFT (`tokenId`) from one account (`from`) to - * another (`to`). - * - * + * @dev Safely transfers `tokenId` token from `from` to `to`, checking first that contract recipients + * are aware of the ERC721 protocol to prevent tokens from being forever locked. * * Requirements: + * * - `from`, `to` cannot be zero. - * - `tokenId` must be owned by `from`. - * - If the caller is not `from`, it must be have been allowed to move this - * NFT by either {approve} or {setApprovalForAll}. + * - `tokenId` token must exist and be owned by `from`. + * - If the caller is not `from`, it must be have been allowed to move this token by either {approve} or {setApprovalForAll}. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + * + * Emits a {Transfer} event. */ function safeTransferFrom(address from, address to, uint256 tokenId) external; + /** - * @dev Transfers a specific NFT (`tokenId`) from one account (`from`) to - * another (`to`). + * @dev Transfers `tokenId` token from `from` to `to`. + * + * WARNING: Usage of this method is discouraged, use {safeTransferFrom} whenever possible. * * Requirements: - * - If the caller is not `from`, it must be approved to move this NFT by - * either {approve} or {setApprovalForAll}. + * + * - `from`, `to` cannot be zero. + * - `tokenId` token must be owned by `from`. + * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. + * + * Emits a {Transfer} event. */ function transferFrom(address from, address to, uint256 tokenId) external; + + /** + * @dev Gives permission to `to` to transfer `tokenId` token to another account. + * The approval is cleared when the token is transferred. + * + * Only a single account can be approved at a time, so approving the zero address clears previous approvals. + * + * Requirements: + * + * - The caller must own the token or be an approved operator. + * - `tokenId` must exist. + * + * Emits an {Approval} event. + */ function approve(address to, uint256 tokenId) external; + + /** + * @dev Returns the account approved for `tokenId` token. + * + * Requirements: + * + * - `tokenId` must exist. + */ function getApproved(uint256 tokenId) external view returns (address operator); + /** + * @dev Approve or remove `operator` as an operator for the caller. + * Operators can call {transferFrom} or {safeTransferFrom} for any token owned by the caller. + * + * Requirements: + * + * - The `operator` cannot be the caller. + * + * Emits an {ApprovalForAll} event. + */ function setApprovalForAll(address operator, bool _approved) external; - function isApprovedForAll(address owner, address operator) external view returns (bool); + /** + * @dev Returns if the `operator` is allowed to manage all of the assets of `owner`. + * + * See {setApprovalForAll} + */ + function isApprovedForAll(address owner, address operator) external view returns (bool); + /** + * @dev Safely transfers `tokenId` token from `from` to `to`. + * + * Requirements: + * + * - `from`, `to` cannot be zero. + * - `tokenId` token must exist and be owned by `from`. + * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}. + * - If `to` refers to a smart contract, it must implement {IERC721Receiver-onERC721Received}, which is called upon a safe transfer. + * + * Emits a {Transfer} event. + */ function safeTransferFrom(address from, address to, uint256 tokenId, bytes calldata data) external; } diff --git a/contracts/token/ERC721/IERC721Enumerable.sol b/contracts/token/ERC721/IERC721Enumerable.sol index db27ee971..1dac81d9d 100644 --- a/contracts/token/ERC721/IERC721Enumerable.sol +++ b/contracts/token/ERC721/IERC721Enumerable.sol @@ -7,8 +7,21 @@ import "./IERC721.sol"; * @dev See https://eips.ethereum.org/EIPS/eip-721 */ interface IERC721Enumerable is IERC721 { + + /** + * @dev Returns the total amount of tokens stored by the contract. + */ function totalSupply() external view returns (uint256); + + /** + * @dev Returns a token ID owned by `owner` at a given `index` of its token list. + * Use along with {balanceOf} to enumerate all of ``owner``'s tokens. + */ function tokenOfOwnerByIndex(address owner, uint256 index) external view returns (uint256 tokenId); + /** + * @dev Returns a token ID at a given `index` of all the tokens stored by the contract. + * Use along with {totalSupply} to enumerate all tokens. + */ function tokenByIndex(uint256 index) external view returns (uint256); } diff --git a/contracts/token/ERC721/IERC721Metadata.sol b/contracts/token/ERC721/IERC721Metadata.sol index 1f9f3d1a9..c7656b570 100644 --- a/contracts/token/ERC721/IERC721Metadata.sol +++ b/contracts/token/ERC721/IERC721Metadata.sol @@ -7,7 +7,19 @@ import "./IERC721.sol"; * @dev See https://eips.ethereum.org/EIPS/eip-721 */ interface IERC721Metadata is IERC721 { + + /** + * @dev Returns the token collection name. + */ function name() external view returns (string memory); + + /** + * @dev Returns the token collection symbol. + */ function symbol() external view returns (string memory); + + /** + * @dev Returns the Uniform Resource Identifier (URI) for `tokenId` token. + */ function tokenURI(uint256 tokenId) external view returns (string memory); }