From 8556bf031c94ea9f547b50cf4c921bb86ed26ab6 Mon Sep 17 00:00:00 2001 From: sotmorskiy Date: Wed, 07 Oct 2020 06:32:21 +0000 Subject: [PATCH] NFTPAR-107: RustDocs for All Externally Callable Methods. --- --- a/pallets/nft/src/lib.rs +++ b/pallets/nft/src/lib.rs @@ -221,8 +221,33 @@ where AccountId = ::AccountId, { + /// New collection was created + /// + /// # Arguments + /// + /// * collection_id: Globally unique identifier of newly created collection. + /// + /// * mode: [CollectionMode] converted into u8. + /// + /// * account_id: Collection owner. Created(u64, u8, AccountId), + + /// New item was created. + /// + /// # Arguments + /// + /// * collection_id: Id of the collection where item was created. + /// + /// * item_id: Id of an item. Unique within the collection. ItemCreated(u64, u64), + + /// Collection item was burned. + /// + /// # Arguments + /// + /// collection_id. + /// + /// item_id: Identifier of burned NFT. ItemDestroyed(u64, u64), } ); @@ -244,9 +269,21 @@ 0 } - // Create collection of NFT with given parameters - // - // @param customDataSz size of custom data in each collection item + /// This method creates a Collection of NFTs. Each Token may have multiple properties encoded as an array of bytes of certain length. The initial owner and admin of the collection are set to the address that signed the transaction. Both addresses can be changed later. + /// + /// # Permissions + /// + /// * Anyone. + /// + /// # Arguments + /// + /// * collection_name: UTF-16 string with collection name (limit 64 characters), will be stored as zero-terminated. + /// + /// * collection_description: UTF-16 string with collection description (limit 256 characters), will be stored as zero-terminated. + /// + /// * token_prefix: UTF-8 string with token prefix. + /// + /// * mode: [CollectionMode] collection type and type dependent data. // returns collection ID #[weight = 0] pub fn create_collection(origin, @@ -316,6 +353,15 @@ Ok(()) } + /// **DANGEROUS**: Destroys collection and all NFTs within this collection. Users irrecoverably lose their assets and may lose real money. + /// + /// # Permissions + /// + /// * Collection Owner. + /// + /// # Arguments + /// + /// * collection_id: collection to destroy. #[weight = 0] pub fn destroy_collection(origin, collection_id: u64) -> DispatchResult { @@ -334,6 +380,18 @@ Ok(()) } + /// Add an address to white list. + /// + /// # Permissions + /// + /// * Collection Owner + /// * Collection Admin + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * address. #[weight = 0] pub fn add_to_white_list(origin, collection_id: u64, address: T::AccountId) -> DispatchResult{ @@ -357,6 +415,18 @@ Ok(()) } + /// Remove an address from white list. + /// + /// # Permissions + /// + /// * Collection Owner + /// * Collection Admin + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * address. #[weight = 0] pub fn remove_from_white_list(origin, collection_id: u64, address: T::AccountId) -> DispatchResult{ @@ -375,6 +445,17 @@ Ok(()) } + /// Toggle between normal and white list access for the methods with access for `Anyone`. + /// + /// # Permissions + /// + /// * Collection Owner. + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * mode: [AccessMode] #[weight = 0] pub fn set_public_access_mode(origin, collection_id: u64, mode: AccessMode) -> DispatchResult { @@ -388,6 +469,19 @@ Ok(()) } + /// Allows Anyone to create tokens if: + /// * White List is enabled, and + /// * Address is added to white list, and + /// * This method was called with True parameter + /// + /// # Permissions + /// * Collection Owner + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * mint_permission: Boolean parameter. If True, allows minting to Anyone with conditions above. #[weight = 0] pub fn set_mint_permission(origin, collection_id: u64, mint_permission: bool) -> DispatchResult { @@ -401,6 +495,17 @@ Ok(()) } + /// Change the owner of the collection. + /// + /// # Permissions + /// + /// * Collection Owner. + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * new_owner. #[weight = 0] pub fn change_collection_owner(origin, collection_id: u64, new_owner: T::AccountId) -> DispatchResult { @@ -413,6 +518,19 @@ Ok(()) } + /// Adds an admin of the Collection. + /// NFT Collection can be controlled by multiple admin addresses (some which can also be servers, for example). Admins can issue and burn NFTs, as well as add and remove other admins, but cannot change NFT or Collection ownership. + /// + /// # Permissions + /// + /// * Collection Owner. + /// * Collection Admin. + /// + /// # Arguments + /// + /// * collection_id: ID of the Collection to add admin for. + /// + /// * new_admin_id: Address of new admin to add. #[weight = 0] pub fn add_collection_admin(origin, collection_id: u64, new_admin_id: T::AccountId) -> DispatchResult { @@ -432,6 +550,18 @@ Ok(()) } + /// Remove admin address of the Collection. An admin address can remove itself. List of admins may become empty, in which case only Collection Owner will be able to add an Admin. + /// + /// # Permissions + /// + /// * Collection Owner. + /// * Collection Admin. + /// + /// # Arguments + /// + /// * collection_id: ID of the Collection to remove admin for. + /// + /// * account_id: Address of admin to remove. #[weight = 0] pub fn remove_collection_admin(origin, collection_id: u64, account_id: T::AccountId) -> DispatchResult { @@ -448,6 +578,15 @@ Ok(()) } + /// # Permissions + /// + /// * Collection Owner + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * new_sponsor. #[weight = 0] pub fn set_collection_sponsor(origin, collection_id: u64, new_sponsor: T::AccountId) -> DispatchResult { @@ -463,6 +602,13 @@ Ok(()) } + /// # Permissions + /// + /// * Sponsor. + /// + /// # Arguments + /// + /// * collection_id. #[weight = 0] pub fn confirm_sponsorship(origin, collection_id: u64) -> DispatchResult { @@ -479,6 +625,15 @@ Ok(()) } + /// Switch back to pay-per-own-transaction model. + /// + /// # Permissions + /// + /// * Collection owner. + /// + /// # Arguments + /// + /// * collection_id. #[weight = 0] pub fn remove_collection_sponsor(origin, collection_id: u64) -> DispatchResult { @@ -494,6 +649,24 @@ Ok(()) } + /// This method creates a concrete instance of NFT Collection created with CreateCollection method. + /// + /// # Permissions + /// + /// * Collection Owner. + /// * Collection Admin. + /// * Anyone if + /// * White List is enabled, and + /// * Address is added to white list, and + /// * MintPermission is enabled (see SetMintPermission method) + /// + /// # Arguments + /// + /// * collection_id: ID of the collection. + /// + /// * properties: Array of bytes that contains NFT properties. Since NFT Module is agnostic of properties meaning, it is treated purely as an array of bytes. + /// + /// * owner: Address, initial owner of the NFT. #[weight = 0] pub fn create_item(origin, collection_id: u64, properties: Vec, owner: T::AccountId) -> DispatchResult { @@ -564,6 +737,19 @@ Ok(()) } + /// Destroys a concrete instance of NFT. + /// + /// # Permissions + /// + /// * Collection Owner. + /// * Collection Admin. + /// * Current NFT Owner. + /// + /// # Arguments + /// + /// * collection_id: ID of the collection. + /// + /// * item_id: ID of NFT to burn. #[weight = 0] pub fn burn_item(origin, collection_id: u64, item_id: u64) -> DispatchResult { @@ -594,6 +780,29 @@ Ok(()) } + /// Change ownership of the token. + /// + /// # Permissions + /// + /// * Collection Owner + /// * Collection Admin + /// * Current NFT owner + /// + /// # Arguments + /// + /// * recipient: Address of token recipient. + /// + /// * collection_id. + /// + /// * item_id: ID of the item + /// * Non-Fungible Mode: Required. + /// * Fungible Mode: Ignored. + /// * Re-Fungible Mode: Required. + /// + /// * value: Amount to transfer. + /// * Non-Fungible Mode: Ignored + /// * Fungible Mode: Must specify transferred amount + /// * Re-Fungible Mode: Must specify transferred portion (between 0 and 1) #[weight = 0] pub fn transfer(origin, recipient: T::AccountId, collection_id: u64, item_id: u64, value: u64) -> DispatchResult { @@ -621,6 +830,21 @@ Ok(()) } + /// Set, change, or remove approved address to transfer the ownership of the NFT. + /// + /// # Permissions + /// + /// * Collection Owner + /// * Collection Admin + /// * Current NFT owner + /// + /// # Arguments + /// + /// * approved: Address that is approved to transfer this NFT or zero (if needed to remove approval). + /// + /// * collection_id. + /// + /// * item_id: ID of the item. #[weight = 0] pub fn approve(origin, approved: T::AccountId, collection_id: u64, item_id: u64) -> DispatchResult { @@ -659,7 +883,26 @@ Ok(()) } - + + /// Change ownership of a NFT on behalf of the owner. See Approve method for additional information. After this method executes, the approval is removed so that the approved address will not be able to transfer this NFT again from this owner. + /// + /// # Permissions + /// * Collection Owner + /// * Collection Admin + /// * Current NFT owner + /// * Address approved by current NFT owner + /// + /// # Arguments + /// + /// * from: Address that owns token. + /// + /// * recipient: Address of token recipient. + /// + /// * collection_id. + /// + /// * item_id: ID of the item. + /// + /// * value: Amount to transfer. #[weight = 0] pub fn transfer_from(origin, from: T::AccountId, recipient: T::AccountId, collection_id: u64, item_id: u64, value: u64 ) -> DispatchResult { @@ -701,6 +944,7 @@ Ok(()) } + /// #[weight = 0] pub fn safe_transfer_from(origin, collection_id: u64, item_id: u64, new_owner: T::AccountId) -> DispatchResult { @@ -716,6 +960,18 @@ Ok(()) } + /// Set off-chain data schema. + /// + /// # Permissions + /// + /// * Collection Owner + /// * Collection Admin + /// + /// # Arguments + /// + /// * collection_id. + /// + /// * schema: String representing the offchain data schema. #[weight = 0] pub fn set_offchain_schema( origin, -- gitstuff