From 0146cb2ffe063dcac811645caa06bff154cd1bae Mon Sep 17 00:00:00 2001
From: Sacha Lansky <sacha@parity.io>
Date: Tue, 15 Aug 2023 12:00:54 +0200
Subject: [PATCH] [fix lint warnings: NFTs pallet] fix
clippy::missing_errors_doc lint warnings (#14648)
* fix missing errors doc warnings
* cargo +nightly fmt
* Update frame/nfts/src/features/create_delete_item.rs
* Update frame/nfts/src/features/create_delete_item.rs
* Update frame/nfts/src/features/transfer.rs
* Update frame/nfts/src/features/create_delete_collection.rs
* add intra doc linking for errors
* fmt
* Apply suggestions from code review
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
---------
Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io>
---
substrate/frame/nfts/src/common_functions.rs | 7 +++-
.../frame/nfts/src/features/attributes.rs | 19 +++++++++--
.../src/features/create_delete_collection.rs | 32 +++++++++++++++++++
.../nfts/src/features/create_delete_item.rs | 26 +++++++++++++++
substrate/frame/nfts/src/features/metadata.rs | 5 +++
substrate/frame/nfts/src/features/transfer.rs | 11 +++++++
6 files changed, 97 insertions(+), 3 deletions(-)
diff --git a/substrate/frame/nfts/src/common_functions.rs b/substrate/frame/nfts/src/common_functions.rs
index b3dcef4cf32..1ad523d664c 100644
--- a/substrate/frame/nfts/src/common_functions.rs
+++ b/substrate/frame/nfts/src/common_functions.rs
@@ -31,7 +31,12 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Collection::<T, I>::get(collection).map(|i| i.owner)
}
- /// Validate the `data` was signed by `signer` and the `signature` is correct.
+ /// Validates the signature of the given data with the provided signer's account ID.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a [`WrongSignature`](crate::Error::WrongSignature) error if the
+ /// signature is invalid or the verification process fails.
pub fn validate_signature(
data: &Vec<u8>,
signature: &T::OffchainSignature,
diff --git a/substrate/frame/nfts/src/features/attributes.rs b/substrate/frame/nfts/src/features/attributes.rs
index 8a9bbe8a61d..29e4de5e273 100644
--- a/substrate/frame/nfts/src/features/attributes.rs
+++ b/substrate/frame/nfts/src/features/attributes.rs
@@ -381,14 +381,24 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(result)
}
- /// A helper method to construct attribute's key.
+ /// A helper method to construct an attribute's key.
+ ///
+ /// # Errors
+ ///
+ /// This function returns an [`IncorrectData`](crate::Error::IncorrectData) error if the
+ /// provided attribute `key` is too long.
pub fn construct_attribute_key(
key: Vec<u8>,
) -> Result<BoundedVec<u8, T::KeyLimit>, DispatchError> {
Ok(BoundedVec::try_from(key).map_err(|_| Error::<T, I>::IncorrectData)?)
}
- /// A helper method to construct attribute's value.
+ /// A helper method to construct an attribute's value.
+ ///
+ /// # Errors
+ ///
+ /// This function returns an [`IncorrectData`](crate::Error::IncorrectData) error if the
+ /// provided `value` is too long.
pub fn construct_attribute_value(
value: Vec<u8>,
) -> Result<BoundedVec<u8, T::ValueLimit>, DispatchError> {
@@ -396,6 +406,11 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
}
/// A helper method to check whether a system attribute is set for a given item.
+ ///
+ /// # Errors
+ ///
+ /// This function returns an [`IncorrectData`](crate::Error::IncorrectData) error if the
+ /// provided pallet attribute is too long.
pub fn has_system_attribute(
collection: &T::CollectionId,
item: &T::ItemId,
diff --git a/substrate/frame/nfts/src/features/create_delete_collection.rs b/substrate/frame/nfts/src/features/create_delete_collection.rs
index aadad58689b..9815958aac7 100644
--- a/substrate/frame/nfts/src/features/create_delete_collection.rs
+++ b/substrate/frame/nfts/src/features/create_delete_collection.rs
@@ -19,6 +19,17 @@ use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Create a new collection with the given `collection`, `owner`, `admin`, `config`, `deposit`,
+ /// and `event`.
+ ///
+ /// This function creates a new collection with the provided parameters. It reserves the
+ /// required deposit from the owner's account, sets the collection details, assigns admin roles,
+ /// and inserts the provided configuration. Finally, it emits the specified event upon success.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a [`CollectionIdInUse`](crate::Error::CollectionIdInUse) error if the
+ /// collection ID is already in use.
pub fn do_create_collection(
collection: T::CollectionId,
owner: T::AccountId,
@@ -56,6 +67,27 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Destroy the specified collection with the given `collection`, `witness`, and
+ /// `maybe_check_owner`.
+ ///
+ /// This function destroys the specified collection if it exists and meets the necessary
+ /// conditions. It checks the provided `witness` against the actual collection details and
+ /// removes the collection along with its associated metadata, attributes, and configurations.
+ /// The necessary deposits are returned to the corresponding accounts, and the roles and
+ /// configurations for the collection are cleared. Finally, it emits the `Destroyed` event upon
+ /// successful destruction.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a dispatch error in the following cases:
+ /// - If the collection ID is not found
+ /// ([`UnknownCollection`](crate::Error::UnknownCollection)).
+ /// - If the provided `maybe_check_owner` does not match the actual owner
+ /// ([`NoPermission`](crate::Error::NoPermission)).
+ /// - If the collection is not empty (contains items)
+ /// ([`CollectionNotEmpty`](crate::Error::CollectionNotEmpty)).
+ /// - If the `witness` does not match the actual collection details
+ /// ([`BadWitness`](crate::Error::BadWitness)).
pub fn do_destroy_collection(
collection: T::CollectionId,
witness: DestroyWitness,
diff --git a/substrate/frame/nfts/src/features/create_delete_item.rs b/substrate/frame/nfts/src/features/create_delete_item.rs
index e3d1334d48e..33af70a9134 100644
--- a/substrate/frame/nfts/src/features/create_delete_item.rs
+++ b/substrate/frame/nfts/src/features/create_delete_item.rs
@@ -19,6 +19,25 @@ use crate::*;
use frame_support::{pallet_prelude::*, traits::ExistenceRequirement};
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Mint a new unique item with the given `collection`, `item`, and other minting configuration
+ /// details.
+ ///
+ /// This function performs the minting of a new unique item. It checks if the item does not
+ /// already exist in the given collection, and if the max supply limit (if configured) is not
+ /// reached. It also reserves the required deposit for the item and sets the item details
+ /// accordingly.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a dispatch error in the following cases:
+ /// - If the collection ID is invalid ([`UnknownCollection`](crate::Error::UnknownCollection)).
+ /// - If the item already exists in the collection
+ /// ([`AlreadyExists`](crate::Error::AlreadyExists)).
+ /// - If the item configuration already exists
+ /// ([`InconsistentItemConfig`](crate::Error::InconsistentItemConfig)).
+ /// - If the max supply limit (if configured) for the collection is reached
+ /// ([`MaxSupplyReached`](crate::Error::MaxSupplyReached)).
+ /// - If any error occurs in the `with_details_and_config` closure.
pub fn do_mint(
collection: T::CollectionId,
item: T::ItemId,
@@ -163,6 +182,13 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
Ok(())
}
+ /// Burns the specified item with the given `collection`, `item`, and `with_details`.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a dispatch error in the following cases:
+ /// - If the collection ID is invalid ([`UnknownCollection`](crate::Error::UnknownCollection)).
+ /// - If the item is locked ([`ItemLocked`](crate::Error::ItemLocked)).
pub fn do_burn(
collection: T::CollectionId,
item: T::ItemId,
diff --git a/substrate/frame/nfts/src/features/metadata.rs b/substrate/frame/nfts/src/features/metadata.rs
index fde0296784d..1493be1d856 100644
--- a/substrate/frame/nfts/src/features/metadata.rs
+++ b/substrate/frame/nfts/src/features/metadata.rs
@@ -209,6 +209,11 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
}
/// A helper method to construct metadata.
+ ///
+ /// # Errors
+ ///
+ /// This function returns an [`IncorrectMetadata`](crate::Error::IncorrectMetadata) dispatch
+ /// error if the provided metadata is too long.
pub fn construct_metadata(
metadata: Vec<u8>,
) -> Result<BoundedVec<u8, T::StringLimit>, DispatchError> {
diff --git a/substrate/frame/nfts/src/features/transfer.rs b/substrate/frame/nfts/src/features/transfer.rs
index 69209e1bb6c..149dbb9646f 100644
--- a/substrate/frame/nfts/src/features/transfer.rs
+++ b/substrate/frame/nfts/src/features/transfer.rs
@@ -19,6 +19,17 @@ use crate::*;
use frame_support::pallet_prelude::*;
impl<T: Config<I>, I: 'static> Pallet<T, I> {
+ /// Performs the transfer action for the given `collection`, `item`, `dest`, and `event`.
+ ///
+ /// # Errors
+ ///
+ /// This function returns a dispatch error in the following cases:
+ /// - If the collection ID is invalid ([`UnknownCollection`](crate::Error::UnknownCollection)).
+ /// - If the item ID is invalid ([`UnknownItem`](crate::Error::UnknownItem)).
+ /// - If the item is locked or transferring it is disabled
+ /// ([`ItemLocked`](crate::Error::ItemLocked)).
+ /// - If the collection or item is non-transferable
+ /// ([`ItemsNonTransferable`](crate::Error::ItemsNonTransferable)).
pub fn do_transfer(
collection: T::CollectionId,
item: T::ItemId,
--
GitLab