Merge pull request #640 from lukso-network/docs/lsp8-preset-extension…

…s-natspec

docs: improve LSP8 preset & extensions Natspec comments + add auto-generated docs

contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol

@@ -38,6 +38,7 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset {
 
      * @param to The address receiving tokens.
      * @param amount The amount of tokens to transfer.
+     * 
      * @return `true` on successful transfer.
      */
     function transfer(address to, uint256 amount) external returns (bool);

contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol

@@ -48,6 +48,7 @@ abstract contract LSP7CappedSupply is LSP7DigitalAsset {
 
     /**
      * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`.
+     *
      * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches
      * reaches {totalSuuplyCap}, it is not possible to mint more tokens.
      *

contracts/LSP7DigitalAsset/presets/LSP7MintableInitAbstract.sol

@@ -11,7 +11,7 @@ import {
 } from "../LSP7DigitalAssetInitAbstract.sol";
 
 /**
- * @dev LSP7 extension, mintable.
+ * @dev LSP7DigitalAsset deployable preset contract (inheritable proxy version) with a public {mint} function callable only by the contract {owner}.
  */
 abstract contract LSP7MintableInitAbstract is
     LSP7DigitalAssetInitAbstract,

contracts/LSP8IdentifiableDigitalAsset/extensions/ILSP8CompatibleERC721.sol

@@ -15,11 +15,14 @@ bytes4 constant _INTERFACEID_ERC721METADATA = 0x5b5e139f;
  */
 interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     /**
-     * @notice To provide compatibility with indexing ERC721 events.
-     * @dev Emitted when `tokenId` token is transferred from `from` to `to`.
-     * @param from The sending address
-     * @param to The receiving address
-     * @param tokenId The tokenId to transfer
+     * @notice ERC721 `Transfer` compatible event emitted. Successfully transferred tokenId `tokenId` from `from` to `to`.
+     *
+     * @dev ERC721 `Transfer` event emitted when `tokenId` token is transferred from `from` to `to`.
+     * To provide compatibility with indexing ERC721 events.
+     *
+     * @param from The sending address.
+     * @param to The receiving address.
+     * @param tokenId The tokenId to transfer.
      */
     event Transfer(
         address indexed from,
@@ -28,21 +31,30 @@ interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     );
 
     /**
-     * @notice To provide compatibility with indexing ERC721 events.
-     * @dev Emitted when `owner` enables `approved` for `tokenId`.
-     * @param owner The address of the owner of the `tokenId`
-     * @param approved The address set as operator
-     * @param tokenId The approved tokenId
+     * @notice ERC721 `Approval` compatible event emitted. Successfully approved operator `operator` to operate on tokenId `tokenId` on behalf of token owner `owner`.
+     *
+     * @dev ERC721 `Approval` event emitted when `owner` enables `operator` for `tokenId`.
+     * To provide compatibility with indexing ERC721 events.
+     *
+     * @param owner The address of the owner of the `tokenId`.
+     * @param operator The address set as operator.
+     * @param tokenId The approved tokenId.
      */
     event Approval(
         address indexed owner,
-        address indexed approved,
+        address indexed operator,
         uint256 indexed tokenId
     );
 
     /**
-     * @dev This emits when an operator is enabled or disabled for an owner.
-     * The operator can manage all NFTs of the owner.
+     * @notice ERC721 `ApprovalForAll` compatible event emitted. Successfully set "approved for all" status to `approved` for operator `operator` for token owner `owner`.
+     *
+     * @dev ERC721 `ApprovalForAll` event emitted when an `operator` is enabled or disabled for an owner
+     * to transfer any of its tokenIds. The operator can manage all NFTs of the owner.
+     *
+     * @param owner The address of the owner of tokenIds.
+     * @param operator The address set as operator.
+     * @param approved If `operator` is approved for all NFTs or not.
      */
     event ApprovalForAll(
         address indexed owner,
@@ -51,18 +63,24 @@ interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     );
 
     /**
-     * @dev Compatible with ERC721 transferFrom.
-     * @param from The sending address
-     * @param to The receiving address
-     * @param tokenId The tokenId to transfer
+     * @notice Calling `transferFrom` function on `ILSP8CompatibleERC721` contract. Transferring tokenId `tokenId` from address `from` to address `to`.
+     *
+     * @dev Transfer functions from the ERC721 standard interface.
+     *
+     * @param from The sending address.
+     * @param to The receiving address.
+     * @param tokenId The tokenId to transfer.
      */
     function transferFrom(address from, address to, uint256 tokenId) external;
 
     /**
-     * @dev Compatible with ERC721 transferFrom.
-     * @param from The sending address
-     * @param to The receiving address
-     * @param tokenId The tokenId to transfer
+     * @notice Calling `safeTransferFrom` function on `ILSP8CompatibleERC721` contract. Transferring tokenId `tokenId` from address `from` to address `to`.
+     *
+     * @dev Safe Transfer function without optional data from the ERC721 standard interface.
+     *
+     * @param from The sending address.
+     * @param to The receiving address.
+     * @param tokenId The tokenId to transfer.
      */
     function safeTransferFrom(
         address from,
@@ -71,11 +89,14 @@ interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     ) external;
 
     /**
-     * @dev Compatible with ERC721 safeTransferFrom.
-     * @param from The sending address
-     * @param to The receiving address
-     * @param tokenId The tokenId to transfer
-     * @param data The data to be sent with the transfer
+     * @notice Calling `safeTransferFrom` function with `data` on `ILSP8CompatibleERC721` contract. Transferring tokenId `tokenId` from address `from` to address `to`.
+     *
+     * @dev Safe Transfer function with optional data from the ERC721 standard interface.
+     *
+     * @param from The sending address.
+     * @param to The receiving address.
+     * @param tokenId The tokenId to transfer.
+     * @param data The data to be sent with the transfer.
      */
     function safeTransferFrom(
         address from,
@@ -85,38 +106,55 @@ interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     ) external;
 
     /**
+     * @notice Retrieving the address that own tokenId `tokenId`.
+     *
      * @dev Compatible with ERC721 ownerOf.
-     * @param tokenId The tokenId to query
-     * @return The owner of the tokenId
+     *
+     * @param tokenId The tokenId to query.
+     * @return The owner of the tokenId.
      */
     function ownerOf(uint256 tokenId) external view returns (address);
 
     /**
-     * @dev Compatible with ERC721 approve.
-     * @param operator The address to approve for `tokenId`
-     * @param tokenId The tokenId to approve
+     * @notice Calling `approve` function on `ILSP8CompatibleERC721` contract. Approving operator at address `operator` to transfer tokenId `tokenId` on behalf of its owner.
+     *
+     * @dev Approval function compatible with ERC721 `approve(address,uint256)`.
+     *
+     * @param operator The address to approve for `tokenId`.
+     * @param tokenId The tokenId to approve.
      */
     function approve(address operator, uint256 tokenId) external;
 
     /**
-     * @notice Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s assets
-     * @dev Emits the ApprovalForAll event. The contract MUST allow multiple operators per owner.
-     * @param _operator Address to add to the set of authorized operators
-     * @param _approved True if the operator is approved, false to revoke approval
+     * @notice Setting the "approval for all" status of operator `_operator` to `_approved` to allow it to transfer any tokenIds on behalf of `msg.sender`.
+     *
+     * @dev Enable or disable approval for a third party ("operator") to manage all of `msg.sender`'s assets. The contract MUST allow multiple operators per owner.
+     *
+     * @param _operator Address to add to the set of authorized operators.
+     * @param _approved True if the operator is approved, false to revoke approval.
+     *
+     * @custom:events {ApprovalForAll} event
      */
     function setApprovalForAll(address _operator, bool _approved) external;
 
     /**
+     * @notice Retrieving the address other than the token owner that is approved to transfer tokenId `tokenId` on behalf of its owner.
+     *
      * @dev Compatible with ERC721 getApproved.
-     * @param tokenId The tokenId to query
-     * @return The address of the operator for `tokenId`
+     *
+     * @param tokenId The tokenId to query.
+     * @return The address of the operator for `tokenId`.
      */
     function getApproved(uint256 tokenId) external view returns (address);
 
     /*
+     * @notice Checking if address `operator` is approved to transfer any tokenId owned by address `owner`.
+     *
      * @dev Compatible with ERC721 isApprovedForAll.
-     * @param owner The tokenOwner address to query
-     * @param operator The operator address to query
+     *
+     * @param owner The tokenOwner address to query.
+     * @param operator The operator address to query.
+     *
      * @return Returns if the `operator` is allowed to manage all of the assets of `owner`
      */
     function isApprovedForAll(
@@ -125,9 +163,13 @@ interface ILSP8CompatibleERC721 is ILSP8IdentifiableDigitalAsset {
     ) external view returns (bool);
 
     /*
+     * @notice Retrieving the token URI of tokenId `tokenId`.
+     *
      * @dev Compatible with ERC721Metadata tokenURI.
-     * @param tokenId The tokenId to query
-     * @return The token URI
+     *
+     * @param tokenId The tokenId to query.
+     *
+     * @return The token URI.
      */
     function tokenURI(uint256 tokenId) external returns (string memory);
 }

contracts/LSP8IdentifiableDigitalAsset/extensions/LSP8Burnable.sol

@@ -9,11 +9,19 @@ import {
 import {LSP8NotTokenOperator} from "../LSP8Errors.sol";
 
 /**
- * @dev LSP8 extension (standard version) that allows token holders to destroy both
+ * @dev LSP8 token extension that allows token holders to destroy both
  * their own tokens and those that they have an allowance for as an operator.
  */
 abstract contract LSP8Burnable is LSP8IdentifiableDigitalAsset {
-    function burn(bytes32 tokenId, bytes memory data) public virtual {
+    /**
+     * @notice Burning tokenId `tokenId`. This tokenId will not be recoverable! (additional data sent: `data`).
+     *
+     * @dev See internal {_burn} function for details.
+     *
+     * @param tokenId The tokenId to burn.
+     * @param data Any extra data to be sent alongside burning the tokenId.
+     */
+    function burn(bytes32 tokenId, bytes memory data) public {
         if (!_isOperatorOrOwner(msg.sender, tokenId)) {
             revert LSP8NotTokenOperator(tokenId, msg.sender);
         }

contracts/LSP8IdentifiableDigitalAsset/extensions/LSP8CappedSupply.sol

@@ -8,19 +8,35 @@ import {
 } from "../LSP8IdentifiableDigitalAsset.sol";
 
 /**
- * @dev LSP8 extension, adds token supply cap.
+ * @dev LSP8 token extension to add a max token supply cap.
  */
 abstract contract LSP8CappedSupply is LSP8IdentifiableDigitalAsset {
     // --- Errors
+
+    /**
+     * @notice The `tokenSupplyCap` must be set and cannot be `0`.
+     * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0.
+     */
     error LSP8CappedSupplyRequired();
+
+    /**
+     * @notice Cannot mint anymore as total supply reached the maximum cap.
+     * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}.
+     */
     error LSP8CappedSupplyCannotMintOverCap();
 
     // --- Storage
     uint256 private immutable _tokenSupplyCap;
 
     /**
-     * @notice Sets the token max supply
-     * @param tokenSupplyCap_ The Token max supply
+     * @notice Deploying a `LSP8CappedSupply` token contract with max token supply cap set to `tokenSupplyCap_`.
+     * @dev Deploy a `LSP8CappedSupply` token contract and set the maximum token supply token cap up to which
+     * it is not possible to mint more tokens.
+     *
+     * @param tokenSupplyCap_ The maximum token supply.
+     *
+     * @custom:requirements
+     * - `tokenSupplyCap_` MUST NOT be 0.
      */
     constructor(uint256 tokenSupplyCap_) {
         if (tokenSupplyCap_ == 0) {
@@ -33,8 +49,12 @@ abstract contract LSP8CappedSupply is LSP8IdentifiableDigitalAsset {
     // --- Token queries
 
     /**
-     * @dev Returns the number of tokens that can be minted.
-     * @return The token max supply
+     * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`.
+     *
+     * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches
+     * reaches {totalSuuplyCap}, it is not possible to mint more tokens.
+     *
+     * @return The maximum number of tokens that can exist in the contract.
      */
     function tokenSupplyCap() public view virtual returns (uint256) {
         return _tokenSupplyCap;
@@ -43,15 +63,13 @@ abstract contract LSP8CappedSupply is LSP8IdentifiableDigitalAsset {
     // --- Transfer functionality
 
     /**
-     * @dev Mints `tokenId` and transfers it to `to`.
-     *
-     * Requirements:
+     * @dev Same as {_mint} but allows to mint only if newly minted `tokenId` does not increase the {totalSupply}
+     * over the {tokenSupplyCap}.
+     * after a new `tokenId` has of tokens have been minted.
      *
-     * - `tokenSupplyCap() - totalSupply()` must be greater than zero.
-     * - `tokenId` must not exist.
+     * @custom:requirements
+     * - {totalSupply} + 1 must not be greater than the {tokenSupplyCap} when calling this function.
      * - `to` cannot be the zero address.
-     *
-     * Emits a {Transfer} event.
      */
     function _mint(
         address to,

contracts/LSP8IdentifiableDigitalAsset/extensions/LSP8CappedSupplyInitAbstract.sol

@@ -8,18 +8,37 @@ import {
 } from "../LSP8IdentifiableDigitalAssetInitAbstract.sol";
 
 /**
- * @dev LSP8 extension, adds token supply cap.
+ * @dev LSP8 token extension to add a max token supply cap.
  */
 abstract contract LSP8CappedSupplyInitAbstract is
     LSP8IdentifiableDigitalAssetInitAbstract
 {
     // --- Errors
+
+    /**
+     * @notice The `tokenSupplyCap` must be set and cannot be `0`.
+     * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0.
+     */
     error LSP8CappedSupplyRequired();
+
+    /**
+     * @notice Cannot mint anymore as total supply reached the maximum cap.
+     * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}.
+     */
     error LSP8CappedSupplyCannotMintOverCap();
 
     // --- Storage
     uint256 private _tokenSupplyCap;
 
+    /**
+     * @dev Initialize a `LSP8CappedSupplyInitAbstract` token contract and set the maximum token supply token cap up to which
+     * it is not possible to mint more tokens.
+     *
+     * @param tokenSupplyCap_ The maximum token supply.
+     *
+     * @custom:requirements
+     * - `tokenSupplyCap_` MUST NOT be 0.
+     */
     function _initialize(
         uint256 tokenSupplyCap_
     ) internal virtual onlyInitializing {
@@ -33,8 +52,12 @@ abstract contract LSP8CappedSupplyInitAbstract is
     // --- Token queries
 
     /**
-     * @dev Returns the number of tokens that can be minted.
-     * @return The token max supply
+     * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`.
+     *
+     * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches
+     * reaches {totalSuuplyCap}, it is not possible to mint more tokens.
+     *
+     * @return The maximum number of tokens that can exist in the contract.
      */
     function tokenSupplyCap() public view virtual returns (uint256) {
         return _tokenSupplyCap;
@@ -43,15 +66,13 @@ abstract contract LSP8CappedSupplyInitAbstract is
     // --- Transfer functionality
 
     /**
-     * @dev Mints `tokenId` and transfers it to `to`.
-     *
-     * Requirements:
+     * @dev Same as {_mint} but allows to mint only if newly minted `tokenId` does not increase the {totalSupply}
+     * over the {tokenSupplyCap}.
+     * after a new `tokenId` has of tokens have been minted.
      *
-     * - `tokenSupplyCap() - totalSupply()` must be greater than zero.
-     * - `tokenId` must not exist.
+     * @custom:requirements
+     * - {totalSupply} + 1 must not be greater than the {tokenSupplyCap} when calling this function.
      * - `to` cannot be the zero address.
-     *
-     * Emits a {Transfer} event.
      */
     function _mint(
         address to,