[fix lint warnings: NFTs pallet] fix clippy::missing_docs_in_private_…

…items warnings (#14610)

* add docs for impl_codec_bitflags

* add missing docs for type aliases

* add docs to transfer module

* add docs for settings module

* add docs to roles module

* add docs to metadata module

* add docs to migration module

* add missing docs to feature library

* methods not functions

* add docs to lock module

* add docs to attributes module

* add docs to create_delete_item module

* add docs for create_delete_collection module

* add docs to buy_sell module

* add missing doc for buy_sell module

* add docs to atomic_swap module

* add docs to atomic_swap module

* add docs for approvals module

* run cargo fmt

* Fix issues with multi-line comments

* Apply suggestions from code review

Co-authored-by: Jegor Sidorenko <5252494+jsidorenko@users.noreply.github.com>

* update from review

* fmt

* update from review

* remove bitflag example

* ".git/.scripts/commands/fmt/fmt.sh"

* Apply suggestions from code review

Co-authored-by: Squirrel <gilescope@gmail.com>

* add note about pallet features

---------

Co-authored-by: Jegor Sidorenko <jegor@parity.io>
Co-authored-by: Jegor Sidorenko <5252494+jsidorenko@users.noreply.github.com>
Co-authored-by: parity-processbot <>
Co-authored-by: Squirrel <gilescope@gmail.com>

frame/nfts/src/features/approvals.rs

@@ -15,10 +15,32 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! This module contains helper functions for the approval logic implemented in the NFTs pallet.
+//! The bitflag [`PalletFeature::Approvals`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
 use crate::*;
 use frame_support::pallet_prelude::*;
 
 impl<T: Config<I>, I: 'static> Pallet<T, I> {
+	/// Approves the transfer of an item to a delegate.
+	///
+	/// This function is used to approve the transfer of the specified `item` in the `collection` to
+	/// a `delegate`. If `maybe_check_origin` is specified, the function ensures that the
+	/// `check_origin` account is the owner of the item, granting them permission to approve the
+	/// transfer. The `delegate` is the account that will be allowed to take control of the item.
+	/// Optionally, a `deadline` can be specified to set a time limit for the approval. The
+	/// `deadline` is expressed in block numbers and is added to the current block number to
+	/// determine the absolute deadline for the approval. After approving the transfer, the function
+	/// emits the `TransferApproved` event.
+	///
+	/// - `maybe_check_origin`: The optional account that is required to be the owner of the item,
+	///   granting permission to approve the transfer. If `None`, no permission check is performed.
+	/// - `collection`: The identifier of the collection containing the item to be transferred.
+	/// - `item`: The identifier of the item to be transferred.
+	/// - `delegate`: The account that will be allowed to take control of the item.
+	/// - `maybe_deadline`: The optional deadline (in block numbers) specifying the time limit for
+	///   the approval.
 	pub(crate) fn do_approve_transfer(
 		maybe_check_origin: Option<T::AccountId>,
 		collection: T::CollectionId,
@@ -63,6 +85,20 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Cancels the approval for the transfer of an item to a delegate.
+	///
+	/// This function is used to cancel the approval for the transfer of the specified `item` in the
+	/// `collection` to a `delegate`. If `maybe_check_origin` is specified, the function ensures
+	/// that the `check_origin` account is the owner of the item or that the approval is past its
+	/// deadline, granting permission to cancel the approval. After canceling the approval, the
+	/// function emits the `ApprovalCancelled` event.
+	///
+	/// - `maybe_check_origin`: The optional account that is required to be the owner of the item or
+	///   that the approval is past its deadline, granting permission to cancel the approval. If
+	///   `None`, no permission check is performed.
+	/// - `collection`: The identifier of the collection containing the item.
+	/// - `item`: The identifier of the item.
+	/// - `delegate`: The account that was previously allowed to take control of the item.
 	pub(crate) fn do_cancel_approval(
 		maybe_check_origin: Option<T::AccountId>,
 		collection: T::CollectionId,
@@ -100,6 +136,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Clears all transfer approvals for an item.
+	///
+	/// This function is used to clear all transfer approvals for the specified `item` in the
+	/// `collection`. If `maybe_check_origin` is specified, the function ensures that the
+	/// `check_origin` account is the owner of the item, granting permission to clear all transfer
+	/// approvals. After clearing all approvals, the function emits the `AllApprovalsCancelled`
+	/// event.
+	///
+	/// - `maybe_check_origin`: The optional account that is required to be the owner of the item,
+	///   granting permission to clear all transfer approvals. If `None`, no permission check is
+	///   performed.
+	/// - `collection`: The collection ID containing the item.
+	/// - `item`: The item ID for which transfer approvals will be cleared.
 	pub(crate) fn do_clear_all_transfer_approvals(
 		maybe_check_origin: Option<T::AccountId>,
 		collection: T::CollectionId,

frame/nfts/src/features/atomic_swap.rs

@@ -15,13 +15,37 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! This module contains helper functions for performing atomic swaps implemented in the NFTs
+//! pallet.
+//! The bitflag [`PalletFeature::Swaps`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
 use crate::*;
 use frame_support::{
 	pallet_prelude::*,
 	traits::{Currency, ExistenceRequirement::KeepAlive},
 };
 
 impl<T: Config<I>, I: 'static> Pallet<T, I> {
+	/// Creates a new swap offer for the specified item.
+	///
+	/// This function is used to create a new swap offer for the specified item. The `caller`
+	/// account must be the owner of the item. The swap offer specifies the `offered_collection`,
+	/// `offered_item`, `desired_collection`, `maybe_desired_item`, `maybe_price`, and `duration`.
+	/// The `duration` specifies the deadline by which the swap must be claimed. If
+	/// `maybe_desired_item` is `Some`, the specified item is expected in return for the swap. If
+	/// `maybe_desired_item` is `None`, it indicates that any item from the `desired_collection` can
+	/// be offered in return. The `maybe_price` specifies an optional price for the swap. If
+	/// specified, the other party must offer the specified `price` or higher for the swap. After
+	/// creating the swap, the function emits the `SwapCreated` event.
+	///
+	/// - `caller`: The account creating the swap offer, which must be the owner of the item.
+	/// - `offered_collection_id`: The collection ID containing the offered item.
+	/// - `offered_item_id`: The item ID offered for the swap.
+	/// - `desired_collection_id`: The collection ID containing the desired item (if any).
+	/// - `maybe_desired_item_id`: The ID of the desired item (if any).
+	/// - `maybe_price`: The optional price for the swap.
+	/// - `duration`: The duration (in block numbers) specifying the deadline for the swap claim.
 	pub(crate) fn do_create_swap(
 		caller: T::AccountId,
 		offered_collection_id: T::CollectionId,
@@ -77,7 +101,16 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 
 		Ok(())
 	}
-
+	/// Cancels the specified swap offer.
+	///
+	/// This function is used to cancel the specified swap offer created by the `caller` account. If
+	/// the swap offer's deadline has not yet passed, the `caller` must be the owner of the offered
+	/// item; otherwise, anyone can cancel an expired offer.
+	/// After canceling the swap offer, the function emits the `SwapCancelled` event.
+	///
+	/// - `caller`: The account canceling the swap offer.
+	/// - `offered_collection_id`: The collection ID containing the offered item.
+	/// - `offered_item_id`: The item ID offered for the swap.
 	pub(crate) fn do_cancel_swap(
 		caller: T::AccountId,
 		offered_collection_id: T::CollectionId,
@@ -107,6 +140,23 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Claims the specified swap offer.
+	///
+	/// This function is used to claim a swap offer specified by the `send_collection_id`,
+	/// `send_item_id`, `receive_collection_id`, and `receive_item_id`. The `caller` account must be
+	/// the owner of the item specified by `send_collection_id` and `send_item_id`. If the claimed
+	/// swap has an associated `price`, it will be transferred between the owners of the two items
+	/// based on the `price.direction`. After the swap is completed, the function emits the
+	/// `SwapClaimed` event.
+	///
+	/// - `caller`: The account claiming the swap offer, which must be the owner of the sent item.
+	/// - `send_collection_id`: The identifier of the collection containing the item being sent.
+	/// - `send_item_id`: The identifier of the item being sent for the swap.
+	/// - `receive_collection_id`: The identifier of the collection containing the item being
+	///   received.
+	/// - `receive_item_id`: The identifier of the item being received in the swap.
+	/// - `witness_price`: The optional witness price for the swap (price that was offered in the
+	///   swap).
 	pub(crate) fn do_claim_swap(
 		caller: T::AccountId,
 		send_collection_id: T::CollectionId,

frame/nfts/src/features/attributes.rs

@@ -15,10 +15,38 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! This module contains helper methods to configure attributes for items and collections in the
+//! NFTs pallet.
+//! The bitflag [`PalletFeature::Attributes`] needs to be set in [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
 use crate::*;
 use frame_support::pallet_prelude::*;
 
 impl<T: Config<I>, I: 'static> Pallet<T, I> {
+	/// Sets the attribute of an item or a collection.
+	///
+	/// This function is used to set an attribute for an item or a collection. It checks the
+	/// provided `namespace` and verifies the permission of the caller to perform the action. The
+	/// `collection` and `maybe_item` parameters specify the target for the attribute.
+	///
+	/// - `origin`: The account attempting to set the attribute.
+	/// - `collection`: The identifier of the collection to which the item belongs, or the
+	///   collection itself if setting a collection attribute.
+	/// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+	///   setting a collection attribute.
+	/// - `namespace`: The namespace in which the attribute is being set. It can be either
+	///   `CollectionOwner`, `ItemOwner`, or `Account` (pre-approved external address).
+	/// - `key`: The key of the attribute. It should be a vector of bytes within the limits defined
+	///   by `T::KeyLimit`.
+	/// - `value`: The value of the attribute. It should be a vector of bytes within the limits
+	///   defined by `T::ValueLimit`.
+	/// - `depositor`: The account that is paying the deposit for the attribute.
+	///
+	/// Note: For the `CollectionOwner` namespace, the collection/item must have the
+	/// `UnlockedAttributes` setting enabled.
+	/// The deposit for setting an attribute is based on the `T::DepositPerByte` and
+	/// `T::AttributeDepositBase` configuration.
 	pub(crate) fn do_set_attribute(
 		origin: T::AccountId,
 		collection: T::CollectionId,
@@ -128,6 +156,23 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Sets the attribute of an item or a collection without performing deposit checks.
+	///
+	/// This function is used to force-set an attribute for an item or a collection without
+	/// performing the deposit checks. It bypasses the deposit requirement and should only be used
+	/// in specific situations where deposit checks are not necessary or handled separately.
+	///
+	/// - `set_as`: The account that would normally pay for the deposit.
+	/// - `collection`: The identifier of the collection to which the item belongs, or the
+	///   collection itself if setting a collection attribute.
+	/// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+	///   setting a collection attribute.
+	/// - `namespace`: The namespace in which the attribute is being set. It can be either
+	///   `CollectionOwner`, `ItemOwner`, or `Account` (pre-approved external address).
+	/// - `key`: The key of the attribute. It should be a vector of bytes within the limits defined
+	///   by `T::KeyLimit`.
+	/// - `value`: The value of the attribute. It should be a vector of bytes within the limits
+	///   defined by `T::ValueLimit`.
 	pub(crate) fn do_force_set_attribute(
 		set_as: Option<T::AccountId>,
 		collection: T::CollectionId,
@@ -159,6 +204,15 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Sets multiple attributes for an item or a collection.
+	///
+	/// This function checks the pre-signed data is valid and updates the attributes of an item or
+	/// collection. It is limited by [`Config::MaxAttributesPerCall`] to prevent excessive storage
+	/// consumption in a single transaction.
+	///
+	/// - `origin`: The account initiating the transaction.
+	/// - `data`: The data containing the details of the pre-signed attributes to be set.
+	/// - `signer`: The account of the pre-signed attributes signer.
 	pub(crate) fn do_set_attributes_pre_signed(
 		origin: T::AccountId,
 		data: PreSignedAttributesOf<T, I>,
@@ -212,6 +266,22 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Clears an attribute of an item or a collection.
+	///
+	/// This function allows clearing an attribute from an item or a collection. It verifies the
+	/// permission of the caller to perform the action based on the provided `namespace` and
+	/// `depositor` account. The deposit associated with the attribute, if any, will be unreserved.
+	///
+	/// - `maybe_check_origin`: An optional account that acts as an additional security check when
+	/// clearing the attribute. This can be `None` if no additional check is required.
+	/// - `collection`: The identifier of the collection to which the item belongs, or the
+	///   collection itself if clearing a collection attribute.
+	/// - `maybe_item`: The identifier of the item to which the attribute belongs, or `None` if
+	///   clearing a collection attribute.
+	/// - `namespace`: The namespace in which the attribute is being cleared. It can be either
+	///   `CollectionOwner`, `ItemOwner`, or `Account`.
+	/// - `key`: The key of the attribute to be cleared. It should be a vector of bytes within the
+	///   limits defined by `T::KeyLimit`.
 	pub(crate) fn do_clear_attribute(
 		maybe_check_origin: Option<T::AccountId>,
 		collection: T::CollectionId,
@@ -288,6 +358,17 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Approves a delegate to set attributes on behalf of the item's owner.
+	///
+	/// This function allows the owner of an item to approve a delegate to set attributes in the
+	/// `Account(delegate)` namespace. The maximum number of approvals is determined by
+	/// the configuration `T::MaxAttributesApprovals`.
+	///
+	/// - `check_origin`: The account of the item's owner attempting to approve the delegate.
+	/// - `collection`: The identifier of the collection to which the item belongs.
+	/// - `item`: The identifier of the item for which the delegate is being approved.
+	/// - `delegate`: The account that is being approved to set attributes on behalf of the item's
+	///   owner.
 	pub(crate) fn do_approve_item_attributes(
 		check_origin: T::AccountId,
 		collection: T::CollectionId,
@@ -312,6 +393,22 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		})
 	}
 
+	/// Cancels the approval of an item's attributes by a delegate.
+	///
+	/// This function allows the owner of an item to cancel the approval of a delegate to set
+	/// attributes in the `Account(delegate)` namespace. The delegate's approval is removed, in
+	/// addition to attributes the `delegate` previously created, and any unreserved deposit
+	/// is returned. The number of attributes that the delegate has set for the item must
+	/// not exceed the `account_attributes` provided in the `witness`.
+	/// This function is used to prevent unintended or malicious cancellations.
+	///
+	/// - `check_origin`: The account of the item's owner attempting to cancel the delegate's
+	///   approval.
+	/// - `collection`: The identifier of the collection to which the item belongs.
+	/// - `item`: The identifier of the item for which the delegate's approval is being canceled.
+	/// - `delegate`: The account whose approval is being canceled.
+	/// - `witness`: The witness containing the number of attributes set by the delegate for the
+	///   item.
 	pub(crate) fn do_cancel_item_attributes_approval(
 		check_origin: T::AccountId,
 		collection: T::CollectionId,
@@ -355,6 +452,7 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		})
 	}
 
+	/// A helper method to check whether an attribute namespace is valid.
 	fn is_valid_namespace(
 		origin: &T::AccountId,
 		namespace: &AttributeNamespace<T::AccountId>,

frame/nfts/src/features/buy_sell.rs

@@ -15,13 +15,28 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! This module contains helper functions to perform the buy and sell functionalities of the NFTs
+//! pallet.
+//! The bitflag [`PalletFeature::Trading`] needs to be set in the [`Config::Features`] for NFTs
+//! to have the functionality defined in this module.
+
 use crate::*;
 use frame_support::{
 	pallet_prelude::*,
 	traits::{Currency, ExistenceRequirement, ExistenceRequirement::KeepAlive},
 };
 
 impl<T: Config<I>, I: 'static> Pallet<T, I> {
+	/// Pays the specified tips to the corresponding receivers.
+	///
+	/// This function is used to pay tips from the `sender` account to multiple receivers. The tips
+	/// are specified as a `BoundedVec` of `ItemTipOf` with a maximum length of `T::MaxTips`. For
+	/// each tip, the function transfers the `amount` to the `receiver` account. The sender is
+	/// responsible for ensuring the validity of the provided tips.
+	///
+	/// - `sender`: The account that pays the tips.
+	/// - `tips`: A `BoundedVec` containing the tips to be paid, where each tip contains the
+	///   `collection`, `item`, `receiver`, and `amount`.
 	pub(crate) fn do_pay_tips(
 		sender: T::AccountId,
 		tips: BoundedVec<ItemTipOf<T, I>, T::MaxTips>,
@@ -40,6 +55,20 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Sets the price and whitelists a buyer for an item in the specified collection.
+	///
+	/// This function is used to set the price and whitelist a buyer for an item in the
+	/// specified `collection`. The `sender` account must be the owner of the item. The item's price
+	/// and the whitelisted buyer can be set to allow trading the item. If `price` is `None`, the
+	/// item will be marked as not for sale.
+	///
+	/// - `collection`: The identifier of the collection containing the item.
+	/// - `item`: The identifier of the item for which the price and whitelist information will be
+	///   set.
+	/// - `sender`: The account that sets the price and whitelist information for the item.
+	/// - `price`: The optional price for the item.
+	/// - `whitelisted_buyer`: The optional account that is whitelisted to buy the item at the set
+	///   price.
 	pub(crate) fn do_set_price(
 		collection: T::CollectionId,
 		item: T::ItemId,
@@ -83,6 +112,19 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		Ok(())
 	}
 
+	/// Buys the specified item from the collection.
+	///
+	/// This function is used to buy an item from the specified `collection`. The `buyer` account
+	/// will attempt to buy the item with the provided `bid_price`. The item's current owner will
+	/// receive the bid price if it is equal to or higher than the item's set price. If
+	/// `whitelisted_buyer` is specified in the item's price information, only that account is
+	/// allowed to buy the item. If the item is not for sale, or the bid price is too low, the
+	/// function will return an error.
+	///
+	/// - `collection`: The identifier of the collection containing the item to be bought.
+	/// - `item`: The identifier of the item to be bought.
+	/// - `buyer`: The account that attempts to buy the item.
+	/// - `bid_price`: The bid price offered by the buyer for the item.
 	pub(crate) fn do_buy_item(
 		collection: T::CollectionId,
 		item: T::ItemId,

frame/nfts/src/features/create_delete_collection.rs

@@ -15,6 +15,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! This module contains helper methods to perform functionality associated with creating and
+//! destroying collections for the NFTs pallet.
+
 use crate::*;
 use frame_support::pallet_prelude::*;