From 19c5277eef20f730516b4db852dda3db16ee7b02 Mon Sep 17 00:00:00 2001 From: DarkLord017 Date: Wed, 15 Jan 2025 23:46:55 +0530 Subject: [PATCH] ref: made rust docs consistent with format specified in #476 --- contracts/src/access/control.rs | 24 +- contracts/src/access/ownable.rs | 12 +- contracts/src/access/ownable_two_step.rs | 19 +- contracts/src/finance/vesting_wallet.rs | 64 ++--- .../src/token/erc1155/extensions/burnable.rs | 34 +-- .../src/token/erc1155/extensions/supply.rs | 24 +- .../token/erc1155/extensions/uri_storage.rs | 8 +- contracts/src/token/erc1155/mod.rs | 264 +++++++++--------- .../src/token/erc20/extensions/burnable.rs | 24 +- .../src/token/erc20/extensions/flash_mint.rs | 26 +- .../src/token/erc20/extensions/metadata.rs | 8 +- .../src/token/erc20/extensions/permit.rs | 47 ++-- contracts/src/token/erc20/mod.rs | 64 ++--- contracts/src/token/erc20/utils/safe_erc20.rs | 66 +++-- .../src/token/erc721/extensions/burnable.rs | 10 +- .../token/erc721/extensions/consecutive.rs | 87 +++--- .../src/token/erc721/extensions/enumerable.rs | 17 +- .../src/token/erc721/extensions/metadata.rs | 16 +- .../token/erc721/extensions/uri_storage.rs | 11 +- contracts/src/token/erc721/mod.rs | 138 ++++----- contracts/src/utils/cryptography/ecdsa.rs | 16 +- contracts/src/utils/nonces.rs | 8 +- contracts/src/utils/pausable.rs | 12 +- contracts/src/utils/reentrant_call_handler.rs | 4 +- 24 files changed, 502 insertions(+), 501 deletions(-) diff --git a/contracts/src/access/control.rs b/contracts/src/access/control.rs index 6942a1d7a..0fd601be3 100644 --- a/contracts/src/access/control.rs +++ b/contracts/src/access/control.rs @@ -215,12 +215,12 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`, then the error is returned. /// /// # Events /// - /// May emit a [`RoleRevoked`] event. + /// * May emit a [`RoleRevoked`] event. pub fn revoke_role( &mut self, role: B256, @@ -251,13 +251,13 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] is not the `confirmation` address, then the error - /// [`Error::BadConfirmation`] is returned. + /// * [`Error::BadConfirmation`] - If [`msg::sender`] is not the + /// `confirmation` address, then the error is returned. /// /// # Events /// - /// If the calling account has its `role` revoked, emits a [`RoleRevoked`] - /// event. + /// * If the calling account has its `role` revoked, emits a [`RoleRevoked`] + /// event. pub fn renounce_role( &mut self, role: B256, @@ -288,7 +288,7 @@ impl AccessControl { /// /// # Events /// - /// Emits a [`RoleAdminChanged`] event. + /// * Emits a [`RoleAdminChanged`] event. pub fn _set_role_admin(&mut self, role: B256, new_admin_role: B256) { let previous_admin_role = self.get_role_admin(role); self._roles.setter(role).admin_role.set(new_admin_role); @@ -309,8 +309,8 @@ impl AccessControl { /// /// # Errors /// - /// If [`msg::sender`] has not been granted `role`, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If [`msg::sender`] has not been + /// granted `role`, then the error is returned. pub fn _check_role( &self, role: B256, @@ -338,7 +338,7 @@ impl AccessControl { /// /// # Events /// - /// May emit a [`RoleGranted`] event. + /// * May emit a [`RoleGranted`] event. pub fn _grant_role(&mut self, role: B256, account: Address) -> bool { if self.has_role(role, account) { false @@ -362,7 +362,7 @@ impl AccessControl { /// /// # Events /// - /// May emit a [`RoleRevoked`] event. + /// * May emit a [`RoleRevoked`] event. pub fn _revoke_role(&mut self, role: B256, account: Address) -> bool { if self.has_role(role, account) { self._roles.setter(role).has_role.insert(account, false); diff --git a/contracts/src/access/ownable.rs b/contracts/src/access/ownable.rs index 2ad282c53..2437011c0 100644 --- a/contracts/src/access/ownable.rs +++ b/contracts/src/access/ownable.rs @@ -120,12 +120,12 @@ pub trait IOwnable { /// /// # Errors /// - /// If not called by the owner, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If not called by the owner, then the error + /// is returned. /// /// # Events /// - /// Emits a [`OwnershipTransferred`] event. + /// * Emits a [`OwnershipTransferred`] event. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; } @@ -170,8 +170,8 @@ impl Ownable { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`Error::UnauthorizedAccount`] is returned. + /// * [`Error::UnauthorizedAccount`] - If called by any account other than the owner, then the error + /// is returned. pub fn only_owner(&self) -> Result<(), Error> { let account = msg::sender(); if self.owner() != account { @@ -193,7 +193,7 @@ impl Ownable { /// /// # Events /// - /// Emits a [`OwnershipTransferred`] event. + /// * Emits a [`OwnershipTransferred`] event. pub fn _transfer_ownership(&mut self, new_owner: Address) { let previous_owner = self._owner.get(); self._owner.set(new_owner); diff --git a/contracts/src/access/ownable_two_step.rs b/contracts/src/access/ownable_two_step.rs index 8dca87d9f..f03502e93 100644 --- a/contracts/src/access/ownable_two_step.rs +++ b/contracts/src/access/ownable_two_step.rs @@ -103,12 +103,12 @@ pub trait IOwnable2Step { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`] - If called by any account other + /// than the owner, then the error is returned. /// /// # Events /// - /// Emits a [`OwnershipTransferStarted`] event. + /// * Emits a [`OwnershipTransferStarted`] event. fn transfer_ownership( &mut self, new_owner: Address, @@ -123,8 +123,8 @@ pub trait IOwnable2Step { /// /// # Errors /// - /// If called by any account other than the pending owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`] - If called by any account other + /// than the pending owner, then the error is returned. /// /// # Events /// @@ -141,12 +141,13 @@ pub trait IOwnable2Step { /// # Arguments /// # Errors /// - /// If not called by the owner, then the error - /// [`OwnableError::UnauthorizedAccount`] is returned. + /// * [`OwnableError::UnauthorizedAccount`]If not called by the owner, then + /// the error + /// is returned. /// /// # Events /// - /// Emits a [`crate::access::ownable::OwnershipTransferred`] event. + /// * Emits a [`crate::access::ownable::OwnershipTransferred`] event. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; } @@ -212,7 +213,7 @@ impl Ownable2Step { /// /// # Events /// - /// Emits a [`crate::access::ownable::OwnershipTransferred`] event. + /// * Emits a [`crate::access::ownable::OwnershipTransferred`] event. fn _transfer_ownership(&mut self, new_owner: Address) { self._pending_owner.set(Address::ZERO); self._ownable._transfer_ownership(new_owner); diff --git a/contracts/src/finance/vesting_wallet.rs b/contracts/src/finance/vesting_wallet.rs index 0e5f52656..25d94dd08 100644 --- a/contracts/src/finance/vesting_wallet.rs +++ b/contracts/src/finance/vesting_wallet.rs @@ -162,14 +162,14 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If called by any account other than the owner, then the error - /// [`ownable::Error::UnauthorizedAccount`] is returned. - /// If `new_owner` is the `Address::ZERO`, then the error - /// [`ownable::Error::InvalidOwner`] is returned. + /// * [`ownable::Error::UnauthorizedAccount`] - If called by any account other than the owner, then the error + /// is returned. + /// * [`ownable::Error::InvalidOwner`] - If `new_owner` is the `Address::ZERO`, then the error + /// is returned. /// /// # Events /// - /// Emits an [`ownable::OwnershipTransferred`] event. + /// * Emits an [`ownable::OwnershipTransferred`] event. fn transfer_ownership( &mut self, new_owner: Address, @@ -190,12 +190,12 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If not called by the owner, then the error - /// [`ownable::Error::UnauthorizedAccount`] is returned. + /// * [`ownable::Error::UnauthorizedAccount`] - If not called by the owner, then the error + /// is returned. /// /// # Events /// - /// Emits an [`ownable::OwnershipTransferred`] event. + /// * Emits an [`ownable::OwnershipTransferred`] event. fn renounce_ownership(&mut self) -> Result<(), Self::Error>; /// The contract should be able to receive Ether. @@ -251,8 +251,8 @@ pub trait IVestingWallet { /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "releasable")] fn releasable_eth(&self) -> U256; @@ -266,13 +266,13 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. + /// * [`Error::InvalidToken`] -If the `token` address is not a contract, then the error + /// is returned. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "releasable")] fn releasable_erc20(&mut self, token: Address) -> Result; @@ -285,17 +285,17 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If Ether transfer fails, then the error [`Error::ReleaseEtherFailed`] is - /// returned. + /// * [`Error::ReleaseEtherFailed`] - If Ether transfer fails, then the error is + /// returned. /// /// # Events /// - /// Emits an [`EtherReleased`] event. + /// * Emits an [`EtherReleased`] event. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "release")] fn release_eth(&mut self) -> Result<(), Self::Error>; @@ -308,19 +308,19 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. - /// If the contract fails to execute the call, then the error - /// [`safe_erc20::Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::InvalidToken`] - If the `token` address is not a contract, then the error + /// is returned. + /// * [`safe_erc20::Error::SafeErc20FailedOperation`] - If the contract fails to execute the call, then the error + /// is returned. /// /// # Events /// - /// Emits an [`ERC20Released`] event. + /// * Emits an [`ERC20Released`] event. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "release")] fn release_erc20(&mut self, token: Address) -> Result<(), Self::Error>; @@ -334,8 +334,8 @@ pub trait IVestingWallet { /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "vestedAmount")] fn vested_amount_eth(&self, timestamp: u64) -> U256; @@ -350,13 +350,13 @@ pub trait IVestingWallet { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::InvalidToken`] is returned. + /// * [`Error::InvalidToken`] - If the `token` address is not a contract, then the error + /// is returned. /// /// # Panics /// - /// If total allocation exceeds `U256::MAX`. - /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`. + /// * If total allocation exceeds `U256::MAX`. + /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`. #[selector(name = "vestedAmount")] fn vested_amount_erc20( &mut self, diff --git a/contracts/src/token/erc1155/extensions/burnable.rs b/contracts/src/token/erc1155/extensions/burnable.rs index bae3789f6..8193ecd6a 100644 --- a/contracts/src/token/erc1155/extensions/burnable.rs +++ b/contracts/src/token/erc1155/extensions/burnable.rs @@ -26,13 +26,13 @@ pub trait IErc1155Burnable { /// /// # Errors /// - /// If the caller is not `account` address and the `account` has not been - /// approved, then the error [`Error::MissingApprovalForAll`] is - /// returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the caller is not `account` + /// address and the `account` has not been approved, then the error is + /// returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the + /// error is returned. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account, then the error is returned. fn burn( &mut self, account: Address, @@ -51,16 +51,16 @@ pub trait IErc1155Burnable { /// /// # Errors /// - /// If the caller is not `account` address and the `account` has not been - /// approved, then the error [`Error::MissingApprovalForAll`] is - /// returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the caller is not `account` + /// address and the `account` has not been approved, then the error is + /// returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the + /// error is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`, then the error is returned. + /// * [`Error::InsufficientBalance`] - If any of the `values` is greater + /// than the balance of the respective token from `tokens` of the `from` + /// account, then the error is returned. fn burn_batch( &mut self, account: Address, diff --git a/contracts/src/token/erc1155/extensions/supply.rs b/contracts/src/token/erc1155/extensions/supply.rs index eb3e4f1ca..cabfe0ee7 100644 --- a/contracts/src/token/erc1155/extensions/supply.rs +++ b/contracts/src/token/erc1155/extensions/supply.rs @@ -196,6 +196,9 @@ impl Erc1155Supply { /// Extended version of [`Erc1155::_update`] that updates the supply of /// tokens. /// + /// NOTE: The ERC-1155 acceptance check is not performed in this function. + /// See [`Self::_update_with_acceptance_check`] instead. + /// /// # Arguments /// /// * `&mut self` - Write access to the contract's state. @@ -206,23 +209,20 @@ impl Erc1155Supply { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the - /// error [`erc1155::Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`erc1155::Error::InsufficientBalance`] is returned. - /// - /// NOTE: The ERC-1155 acceptance check is not performed in this function. - /// See [`Self::_update_with_acceptance_check`] instead. + /// * [`erc1155::Error::InvalidArrayLength`] - If length of `ids` is not + /// equal to length of `values`, then the error is returned. + /// * [`erc1155::Error::InsufficientBalance`] - If `value` is greater than + /// the balance of the `from` account, then the error is returned. /// /// # Events /// - /// Emits a [`erc1155::TransferSingle`] event if the arrays contain one - /// element, and [`erc1155::TransferBatch`] otherwise. + /// * Emits a [`erc1155::TransferSingle`] event if the arrays contain one + /// element, and [`erc1155::TransferBatch`] otherwise. /// - /// # Panics + /// # Panics /// - /// If updated balance and/or supply exceeds `U256::MAX`, may happen during - /// the `mint` operation. + /// * If updated balance and/or supply exceeds `U256::MAX`, may happen + /// during the `mint` operation. fn _update( &mut self, from: Address, diff --git a/contracts/src/token/erc1155/extensions/uri_storage.rs b/contracts/src/token/erc1155/extensions/uri_storage.rs index 0c62d875d..ecdb4dd6d 100644 --- a/contracts/src/token/erc1155/extensions/uri_storage.rs +++ b/contracts/src/token/erc1155/extensions/uri_storage.rs @@ -26,6 +26,9 @@ pub struct Erc1155UriStorage { impl Erc1155UriStorage { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI, + /// you need to do this manually. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -33,9 +36,6 @@ impl Erc1155UriStorage { /// * `metadata_uri` - Read access to a contract providing /// [`IErc1155MetadataUri`] interface. /// - /// NOTE: In order to have [`Erc1155UriStorage::uri`] exposed in ABI, - /// you need to do this manually. - /// /// # Examples /// /// ```rust,ignore @@ -68,7 +68,7 @@ impl Erc1155UriStorage { /// /// # Events /// - /// Emits a [`URI`] event. + /// * Emits a [`URI`] event. pub fn set_token_uri( &mut self, token_id: U256, diff --git a/contracts/src/token/erc1155/mod.rs b/contracts/src/token/erc1155/mod.rs index ae93e4764..d4bf1cbb6 100644 --- a/contracts/src/token/erc1155/mod.rs +++ b/contracts/src/token/erc1155/mod.rs @@ -239,8 +239,9 @@ pub trait IErc1155 { /// /// # Errors /// - /// * If the length of `accounts` is not equal to the length of `ids`, - /// then the error [`Error::InvalidArrayLength`] is returned. + /// * [`Error::InvalidArrayLength`] - If the length of `accounts` is not + /// equal to the length of `ids`, + /// then the error is returned. fn balance_of_batch( &self, accounts: Vec
, @@ -260,8 +261,8 @@ pub trait IErc1155 { /// /// # Errors /// - /// * If `operator` is `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. + /// * [`Error::InvalidOperator`] - If `operator` is `Address::ZERO`, then + /// the error is returned. /// /// # Requirements /// @@ -301,18 +302,15 @@ pub trait IErc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`]: Returned when `to` is `Address::ZERO` or + /// when `IERC1155Receiver::on_erc_1155_received` hasn't returned its + /// interface id or returned with error + /// * [`Error::InvalidSender`]: Returned when `from` is `Address::ZERO` + /// * []`Error::MissingApprovalForAll`]: Returned when `from` is not the + /// caller (`msg::sender()`), and the caller does not have the right to + /// approve + /// * [`Error::InsufficientBalance`]: Returned when `value` is greater than + /// the balance of the `from` account /// /// # Requirements /// @@ -325,13 +323,13 @@ pub trait IErc1155 { /// [`IERC1155Receiver::on_erc_1155_received`] and return the acceptance /// value. /// - /// # Events + /// # Panics /// - /// Emits a [`TransferSingle`] event. + /// * Should not panic. /// - /// # Panics + /// # Events /// - /// Should not panic. + /// Emits a [`TransferSingle`] event. fn safe_transfer_from( &mut self, from: Address, @@ -354,21 +352,17 @@ pub trait IErc1155 { /// `to`. /// /// # Errors - /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`]: Returned when `to` is `Address::ZERO` or + /// when `IERC1155Receiver::on_erc_1155_batch_received` hasn't returned + /// its interface id or returned with error + /// * [`Error::InvalidSender`]: Returned when `from` is `Address::ZERO` + /// * [`Error::InvalidArrayLength`]: Returned when the length of `ids` is + /// not equal to the length of `values` + /// * [`Error::InsufficientBalance`]: Returned when any of the `values` is + /// greater than the balance of the `from` account + /// * [`Error::MissingApprovalForAll`]: Returned when `from` is not the + /// caller (`msg::sender()`), and the caller does not have the right to + /// approve /// /// # Requirements /// @@ -382,14 +376,14 @@ pub trait IErc1155 { /// [`IERC1155Receiver::on_erc_1155_batch_received`] and return the /// acceptance magic value. /// + /// # Panics + /// + /// * Should not panic. + /// /// # Events /// /// Emits either a [`TransferSingle`] or a [`TransferBatch`] event, /// depending on the length of the array arguments. - /// - /// # Panics - /// - /// Should not panic. fn safe_batch_transfer_from( &mut self, from: Address, @@ -542,26 +536,27 @@ impl Erc1155 { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidArrayLength`] - Returned when length of `ids` is not + /// equal to length of `values`. + ///[`Error::InsufficientBalance`] - Returned when `value` is greater than + /// the balance of the `from` account + /// * [`Error::InvalidReceiver`] - Returned + /// when`IERC1155Receiver::on_erc_1155_received` hasn't returned its + /// interface + /// id or returned with error. + /// * [`Error::InvalidReceiver`] - Returned when + /// `IERC1155Receiver::on_erc_1155_batch_received` hasn't returned its + /// interface id or returned with error. + /// + /// # Panics + /// + /// * If updated balance exceeds `U256::MAX`, may happen during `mint` + /// operation. /// /// # Events /// /// Emits a [`TransferSingle`] event if the arrays contain one element, and /// [`TransferBatch`] otherwise. - /// - /// # Panics - /// - /// If updated balance exceeds `U256::MAX`, may happen during `mint` - /// operation. fn _update_with_acceptance_check( &mut self, from: Address, @@ -635,25 +630,24 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// - /// # Events + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`, then the error is returned. + /// * [`IERC1155Receiver::on_erc_1155_received`] - If hasn't returned its + /// * [`Error::InvalidReceiver`] - interface id or returned with error, then + /// the error is returned. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// interface id or returned with error, then the error is returned. + /// # Panics /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * If updated balance exceeds `U256::MAX`. /// - /// # Panics + /// # Events /// - /// If updated balance exceeds `U256::MAX`. + /// * Emits a [`TransferSingle`] event if the arrays contain one element, + /// and [`TransferBatch`] otherwise. pub fn _mint_batch( &mut self, to: Address, @@ -675,18 +669,18 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the balance of the `from` account, + /// then the error is returned. /// /// # Events /// - /// Emits a [`TransferSingle`] event. + /// * Emits a [`TransferSingle`] event. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. pub fn _burn( &mut self, from: Address, @@ -707,22 +701,21 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to length of `values`, then the + /// error is returned. + /// * [`Error::InsufficientBalance`] - If any of the `values` is greater than the balance of the respective + /// token from `tokens` of the `from` account, then the error is returned. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * Emits a [`TransferSingle`] event if the arrays contain one element, and + /// [`TransferBatch`] otherwise. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. pub fn _burn_batch( &mut self, from: Address, @@ -745,12 +738,12 @@ impl Erc1155 { /// /// # Errors /// - /// If `operator` is the `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. + /// * [`Error::InvalidOperator`] - If `operator` is the `Address::ZERO`, then the error + /// is returned. /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * Emits an [`ApprovalForAll`] event. fn _set_approval_for_all( &mut self, owner: Address, @@ -795,12 +788,12 @@ impl Erc1155 { /// /// # Errors /// - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// is returned. + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// is returned. fn _check_on_erc1155_received( &mut self, operator: Address, @@ -864,25 +857,25 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// is returned. + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to length of `values`, then the + /// error is returned. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and + /// * Emits a [`TransferSingle`] event if the arrays contain one element, and /// [`TransferBatch`] otherwise. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn _do_mint( &mut self, to: Address, @@ -916,22 +909,21 @@ impl Erc1155 { /// /// # Errors /// - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If any of the `values` is greater than the balance of the respective - /// token from `tokens` of the `from` account, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to length of `values`, then the + /// error is returned. + /// * [`Error::InsufficientBalance`] -If any of the `values` is greater than the balance of the respective + /// token from `tokens` of the `from` account, then the error is returned. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * Emits a [`TransferSingle`] event if the arrays contain one element, and + /// [`TransferBatch`] otherwise. /// /// # Panics /// - /// Should not panic. + /// * Should not panic. fn _do_burn( &mut self, from: Address, @@ -967,29 +959,29 @@ impl Erc1155 { /// /// # Errors /// - /// If `to` is the `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `from` is the `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If length of `ids` is not equal to length of `values`, then the - /// error [`Error::InvalidArrayLength`] is returned. - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its + /// * [`Error::InvalidReceiver`] - If `to` is the `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InvalidSender`] - If `from` is the `Address::ZERO`, then the error + /// is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to length of `values`, then the + /// error is returned. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the balance of the `from` account, + /// then the error is returned. + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its + /// is returned. + /// * [`Error::InvalidReceiver`] - If [`IERC1155Receiver::on_erc_1155_batch_received`] hasn't returned its /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// is returned. /// /// # Events /// - /// Emits a [`TransferSingle`] event if the arrays contain one element, and - /// [`TransferBatch`] otherwise. + /// * Emits a [`TransferSingle`] event if the arrays contain one element, and + /// [`TransferBatch`] otherwise. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn do_safe_transfer_from( &mut self, from: Address, @@ -1024,12 +1016,12 @@ impl Erc1155 { /// /// # Errors /// - /// If `value` is greater than the balance of the `from` account, - /// then the error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientBalance`] - If `value` is greater than the + /// balance of the `from` account, then the error is returned. /// /// # Panics /// - /// If updated balance exceeds `U256::MAX`. + /// * If updated balance exceeds `U256::MAX`. fn do_update( &mut self, from: Address, @@ -1074,8 +1066,8 @@ impl Erc1155 { /// /// # Errors /// - /// If length of `ids` is not equal to length of `values`, then the error - /// [`Error::InvalidArrayLength`] is returned. + /// * [`Error::InvalidArrayLength`] - If length of `ids` is not equal to + /// length of `values`, then the error is returned. fn require_equal_arrays_length( ids: &[T], values: &[U], @@ -1098,9 +1090,9 @@ impl Erc1155 { /// /// # Errors /// - /// If the `from` is not the caller (`msg::sender()`), - /// and the caller does not have the right to approve, then the error - /// [`Error::MissingApprovalForAll`] is returned. + /// * [`Error::MissingApprovalForAll`] - If the `from` is not the caller + /// (`msg::sender()`), and the caller does not have the right to approve, + /// then the error is returned. fn authorize_transfer(&self, from: Address) -> Result<(), Error> { let sender = msg::sender(); if from != sender && !self.is_approved_for_all(from, sender) { diff --git a/contracts/src/token/erc20/extensions/burnable.rs b/contracts/src/token/erc20/extensions/burnable.rs index 683531720..a269a7c45 100644 --- a/contracts/src/token/erc20/extensions/burnable.rs +++ b/contracts/src/token/erc20/extensions/burnable.rs @@ -15,7 +15,7 @@ pub trait IErc20Burnable { /// Destroys a `value` amount of tokens from the caller, lowering the total /// supply. /// - /// Relies on the `update` mechanism. + /// NOTE: Relies on the `update` mechanism. /// /// # Arguments /// @@ -23,18 +23,18 @@ pub trait IErc20Burnable { /// /// # Errors /// - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens, then the error is returned. /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * Emits a [`super::super::Transfer`] event. fn burn(&mut self, value: U256) -> Result<(), Self::Error>; /// Destroys a `value` amount of tokens from `account`, lowering the total /// supply. /// - /// Relies on the `update` mechanism. + /// NOTE: Relies on the `update` mechanism. /// /// # Arguments /// @@ -43,16 +43,16 @@ pub trait IErc20Burnable { /// /// # Errors /// - /// If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. - /// If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available, then the error is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens, then the error is returned. /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * Emits a [`super::super::Transfer`] event. fn burn_from( &mut self, account: Address, diff --git a/contracts/src/token/erc20/extensions/flash_mint.rs b/contracts/src/token/erc20/extensions/flash_mint.rs index 9f1629941..9028268dd 100644 --- a/contracts/src/token/erc20/extensions/flash_mint.rs +++ b/contracts/src/token/erc20/extensions/flash_mint.rs @@ -172,8 +172,8 @@ pub trait IErc3156FlashLender { /// /// # Errors /// - /// * If the token is not supported, then the error - /// [`Error::UnsupportedToken`] is returned. + /// * [`Error::UnsupportedToken`] - If the token is not supported, then the + /// error is returned. /// /// # Examples /// @@ -213,17 +213,17 @@ pub trait IErc3156FlashLender { /// /// # Errors /// - /// * If the `value` is greater than the value returned by - /// [`IErc3156FlashLender::max_flash_loan`], then the error - /// [`Error::ExceededMaxLoan`] is returned. - /// * If `token` is not supported, then the error - /// [`Error::UnsupportedToken`] is returned. - /// * If the `token` address is not a contract, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the contract fails to execute the call, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the receiver does not return [`BORROWER_CALLBACK_VALUE`], then the - /// error [`Error::InvalidReceiver`] is returned. + /// * [`Error::ExceededMaxLoan`] - If the `value` is greater than the value + /// returned by [`IErc3156FlashLender::max_flash_loan`], then the error is + /// returned. + /// * [`Error::UnsupportedToken`] - If `token` is not supported, then the + /// error is returned. + /// * [`Error::InvalidReceiver`] - If the `token` address is not a contract, + /// then the error is returned. + /// * [`Error::InvalidReceiver`] - If the contract fails to execute the + /// call, then the error is returned. + /// * [`Error::InvalidReceiver`] - If the receiver does not return + /// [`BORROWER_CALLBACK_VALUE`], then the error is returned. /// /// # Events /// diff --git a/contracts/src/token/erc20/extensions/metadata.rs b/contracts/src/token/erc20/extensions/metadata.rs index 3e7d0db99..e5ac874df 100644 --- a/contracts/src/token/erc20/extensions/metadata.rs +++ b/contracts/src/token/erc20/extensions/metadata.rs @@ -52,14 +52,14 @@ pub trait IErc20Metadata { /// between Ether and Wei. This is the default value returned by this /// function ([`DEFAULT_DECIMALS`]), unless it's overridden. /// - /// # Arguments - /// - /// * `&self` - Read access to the contract's state. - /// /// NOTE: This information is only used for *display* purposes: in /// no way it affects any of the arithmetic of the contract, including /// [`super::super::IErc20::balance_of`] and /// [`super::super::IErc20::transfer`]. + /// + /// # Arguments + /// + /// * `&self` - Read access to the contract's state. fn decimals(&self) -> u8; } diff --git a/contracts/src/token/erc20/extensions/permit.rs b/contracts/src/token/erc20/extensions/permit.rs index d46dd8f4d..205ffa99e 100644 --- a/contracts/src/token/erc20/extensions/permit.rs +++ b/contracts/src/token/erc20/extensions/permit.rs @@ -131,16 +131,16 @@ impl Erc20Permit { /// /// # Errors /// - /// If the `deadline` param is from the past, than the error - /// [`ERC2612ExpiredSignature`] is returned. - /// If signer is not an `owner`, than the error - /// [`ERC2612InvalidSigner`] is returned. - /// * If the `s` value is grater than [`ecdsa::SIGNATURE_S_UPPER_BOUND`], - /// then the error [`ecdsa::Error::InvalidSignatureS`] is returned. - /// * If the recovered address is `Address::ZERO`, then the error - /// [`ecdsa::Error::InvalidSignature`] is returned. - /// If the `spender` address is `Address::ZERO`, then the error - /// [`erc20::Error::InvalidSpender`] is returned. + /// * [`ERC2612ExpiredSignature`] - If the `deadline` param is from the + /// past, than the error is returned. + /// * [`ERC2612InvalidSigner`] - If signer is not an `owner`, than the error + /// is returned. + /// * [`ecdsa::Error::InvalidSignatureS`] - If the `s` value is grater than + /// [`ecdsa::SIGNATURE_S_UPPER_BOUND`], then the error is returned. + /// * [`ecdsa::Error::InvalidSignature`] - If the recovered address is + /// `Address::ZERO`, then the error is returned. + /// * [`erc20::Error::InvalidSpender`] - If the `spender` address is + /// `Address::ZERO`, then the error is returned. /// /// # Events /// @@ -221,10 +221,11 @@ impl Erc20Permit { /// /// # Errors /// - /// * If the `to` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidReceiver`] is returned. - /// * If the caller doesn't have a balance of at least `value`, then the - /// error [`crate::token::erc20::Error::InsufficientBalance`] is returned. + /// * [`crate::token::erc20::Error::InvalidReceiver`] - If the `to` address + /// is `Address::ZERO`, then the error is returned. + /// * [`crate::token::erc20::Error::InsufficientBalance`] - If the caller + /// doesn't have a balance of at least `value`, then the error is + /// returned. /// /// # Events /// @@ -273,8 +274,8 @@ impl Erc20Permit { /// /// # Errors /// - /// If the `spender` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidSpender`] is returned. + /// [`crate::token::erc20::Error::InvalidSpender`] - If the `spender` + /// address is `Address::ZERO`, then the error is returned. /// /// # Events /// @@ -306,16 +307,16 @@ impl Erc20Permit { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`crate::token::erc20::Error::InvalidReceiver`] is returned. - /// * If not enough allowance is available, then the error - /// [`crate::token::erc20::Error::InsufficientAllowance`] is returned. + /// * [`crate::token::erc20::Error::InvalidSender`] - If the `from` address + /// is `Address::ZERO`, then the error is returned. + /// * [`crate::token::erc20::Error::InvalidReceiver`] - If the `to` address + /// is `Address::ZERO`, then the error is returned. + /// * [`crate::token::erc20::Error::InsufficientAllowance`] - If not enough + /// allowance is available, then the error is returned. /// /// # Events /// - /// Emits a [`crate::token::erc20::Transfer`] event. + /// * Emits a [`crate::token::erc20::Transfer`] event. pub fn transfer_from( &mut self, from: Address, diff --git a/contracts/src/token/erc20/mod.rs b/contracts/src/token/erc20/mod.rs index cf20cfa7d..169dc7efc 100644 --- a/contracts/src/token/erc20/mod.rs +++ b/contracts/src/token/erc20/mod.rs @@ -171,10 +171,10 @@ pub trait IErc20 { /// /// # Errors /// - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the caller doesn't have a balance of at least `value`, then the - /// error [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InsufficientBalance`] - If the caller doesn't have a balance + /// of at least `value`, then the error is returned. /// /// # Events /// @@ -218,8 +218,8 @@ pub trait IErc20 { /// /// # Errors /// - /// If the `spender` address is `Address::ZERO`, then the error - /// [`Error::InvalidSpender`] is returned. + /// * [`Error::InvalidSpender`] - If the `spender` address is + /// `Address::ZERO`, then the error is returned. /// /// # Events /// @@ -249,12 +249,12 @@ pub trait IErc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available, then the error is returned. /// /// # Events /// @@ -379,12 +379,12 @@ impl Erc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `to` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// * If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InvalidReceiver`] - If the `to` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens, then the error is returned. /// /// # Events /// @@ -422,8 +422,8 @@ impl Erc20 { /// /// # Errors /// - /// If the `account` address is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If the `account` address is + /// `Address::ZERO`, then the error is returned. /// /// # Events /// @@ -453,15 +453,15 @@ impl Erc20 { /// * `to` - Recipient's address. /// * `value` - Amount to be transferred. /// - /// # Panics + /// # Errors /// - /// If `_total_supply` exceeds `U256::MAX`. It may happen during `mint` - /// operation. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens, then the error is returned. /// - /// # Errors + /// # Panics /// - /// If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * If `_total_supply` exceeds `U256::MAX`. It may happen during `mint` + /// operation. /// /// # Events /// @@ -524,10 +524,10 @@ impl Erc20 { /// /// # Errors /// - /// * If the `from` address is `Address::ZERO`, then the error - /// [`Error::InvalidSender`] is returned. - /// * If the `from` address doesn't have enough tokens, then the error - /// [`Error::InsufficientBalance`] is returned. + /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`, + /// then the error is returned. + /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have + /// enough tokens, then the error is returned. /// /// # Events /// @@ -558,8 +558,8 @@ impl Erc20 { /// /// # Errors /// - /// If not enough allowance is available, then the error - /// [`Error::InsufficientAllowance`] is returned. + /// * [`Error::InsufficientAllowance`] - If not enough allowance is + /// available, then the error is returned. /// /// # Events /// diff --git a/contracts/src/token/erc20/utils/safe_erc20.rs b/contracts/src/token/erc20/utils/safe_erc20.rs index 7066a1b8a..6e15ee9f3 100644 --- a/contracts/src/token/erc20/utils/safe_erc20.rs +++ b/contracts/src/token/erc20/utils/safe_erc20.rs @@ -166,16 +166,16 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`, then the error is returned. /// /// # Panics /// - /// If increased allowance exceeds `U256::MAX`. + /// * If increased allowance exceeds `U256::MAX`. fn safe_increase_allowance( &mut self, token: Address, @@ -196,14 +196,15 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the current allowance is less than `requested_decrease`, then the - /// error [`Error::SafeErc20FailedDecreaseAllowance`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract, then the error is returned. + /// * [`Error::SafeErc20FailedDecreaseAllowance`] - If the current allowance + /// is less than `requested_decrease`, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`, then the error is returned. + fn safe_decrease_allowance( &mut self, token: Address, @@ -225,12 +226,13 @@ pub trait ISafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`, then the error is returned. + fn force_approve( &mut self, token: Address, @@ -337,12 +339,13 @@ impl SafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to execute the call, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the call returns value that is not `true`, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to execute + /// the call, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the call returns value that + /// is not `true`, then the error is returned. + fn call_optional_return( token: Address, call: &impl SolCall, @@ -370,10 +373,11 @@ impl SafeErc20 { /// /// # Errors /// - /// If the `token` address is not a contract, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. - /// If the contract fails to read `spender`'s allowance, then the error - /// [`Error::SafeErc20FailedOperation`] is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the `token` address is not a + /// contract, then the error is returned. + /// * [`Error::SafeErc20FailedOperation`] - If the contract fails to read + /// `spender`'s allowance, then the error is returned. + fn allowance(token: Address, spender: Address) -> Result { if !Address::has_code(&token) { return Err(SafeErc20FailedOperation { token }.into()); diff --git a/contracts/src/token/erc721/extensions/burnable.rs b/contracts/src/token/erc721/extensions/burnable.rs index f06a90535..e74542f57 100644 --- a/contracts/src/token/erc721/extensions/burnable.rs +++ b/contracts/src/token/erc721/extensions/burnable.rs @@ -21,10 +21,10 @@ pub trait IErc721Burnable { /// /// # Errors /// - /// If token does not exist, then the error [`Error::NonexistentToken`] is - /// returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. + /// * [`Error::NonexistentToken`] - If token does not exist, then the error + /// is returned. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve, then the error is returned. /// /// # Requirements: /// @@ -33,7 +33,7 @@ pub trait IErc721Burnable { /// /// # Events /// - /// Emits a [`super::super::Transfer`] event. + /// * Emits a [`super::super::Transfer`] event. fn burn(&mut self, token_id: U256) -> Result<(), Self::Error>; } diff --git a/contracts/src/token/erc721/extensions/consecutive.rs b/contracts/src/token/erc721/extensions/consecutive.rs index 8211493f0..8b787a00b 100644 --- a/contracts/src/token/erc721/extensions/consecutive.rs +++ b/contracts/src/token/erc721/extensions/consecutive.rs @@ -367,15 +367,15 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If token does not exist and `auth` is not `Address::ZERO`, then the - /// error [`erc721::Error::NonexistentToken`] is returned. - /// If `auth` is not `Address::ZERO` and `auth` does not have a right to - /// approve this token, then the error - /// [`erc721::Error::InsufficientApproval`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If token does not exist and + /// `auth` is not `Address::ZERO`, then the error is returned. + /// * [`erc721::Error::InsufficientApproval`] - If `auth` is not + /// `Address::ZERO` and `auth` does not have a right to approve this + /// token, then the error is returned. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _update( &mut self, to: Address, @@ -489,10 +489,10 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`erc721::Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. + /// * [`erc721::Error::InvalidSender`] - If `token_id` already exists, then + /// the error is returned. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then + /// the error is returned. /// /// # Requirements: /// @@ -501,7 +501,7 @@ impl Erc721Consecutive { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _mint(&mut self, to: Address, token_id: U256) -> Result<(), Error> { if to.is_zero() { return Err(erc721::Error::InvalidReceiver( @@ -536,13 +536,13 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`erc721::Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If [`erc721::IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. + /// * [`erc721::Error::InvalidSender`] - If `token_id` already exists, then + /// the error is returned. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then + /// the error is returned. + /// * [`erc721::Error::InvalidReceiver`] - If + /// [`erc721::IERC721Receiver::on_erc_721_received`] hasn't returned its + /// interface id or returned with error, then the error is returned. /// /// # Requirements: /// @@ -553,7 +553,7 @@ impl Erc721Consecutive { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _safe_mint( &mut self, to: Address, @@ -583,8 +583,8 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If token does not exist, then + /// the error is returned. /// /// # Requirements: /// @@ -592,7 +592,7 @@ impl Erc721Consecutive { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _burn(&mut self, token_id: U256) -> Result<(), Error> { let previous_owner = self._update(Address::ZERO, token_id, Address::ZERO)?; @@ -619,12 +619,12 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`erc721::Error::IncorrectOwner`] is returned. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then + /// the error is returned. + /// * [`erc721::Error::NonexistentToken`] - If `token_id` does not exist, + /// then the error is returned. + /// * [`erc721::Error::IncorrectOwner`] - If the previous owner is not + /// `from`, then the error is returned. /// /// # Requirements: /// @@ -633,7 +633,7 @@ impl Erc721Consecutive { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _transfer( &mut self, from: Address, @@ -687,12 +687,12 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`erc721::Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`erc721::Error::IncorrectOwner`] is returned. + /// * [`erc721::Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then + /// the error is returned. + /// * [`erc721::Error::NonexistentToken`] - If `token_id` does not exist, + /// then the error is returned. + /// * [`erc721::Error::IncorrectOwner`] - If the previous owner is not + /// `from`, then the error is returned. /// /// # Requirements: /// @@ -704,8 +704,7 @@ impl Erc721Consecutive { /// a `safe_transfer`. /// /// # Events - /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _safe_transfer( &mut self, from: Address, @@ -740,14 +739,14 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. - /// If `auth` does not have a right to approve this token, then the error - /// [`erc721::Error::InvalidApprover`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If the token does not exist, + /// then the error is returned. + /// * [`erc721::Error::InvalidApprover`] - If `auth` does not have a right + /// to approve this token, then the error is returned. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * Emits an [`Approval`] event. pub fn _approve( &mut self, to: Address, @@ -788,8 +787,8 @@ impl Erc721Consecutive { /// /// # Errors /// - /// If token does not exist, then the error - /// [`erc721::Error::NonexistentToken`] is returned. + /// * [`erc721::Error::NonexistentToken`] - If token does not exist, then + /// the error is returned. /// /// # Arguments /// diff --git a/contracts/src/token/erc721/extensions/enumerable.rs b/contracts/src/token/erc721/extensions/enumerable.rs index 34e3dc901..cdb519672 100644 --- a/contracts/src/token/erc721/extensions/enumerable.rs +++ b/contracts/src/token/erc721/extensions/enumerable.rs @@ -124,8 +124,9 @@ pub trait IErc721Enumerable { /// /// # Errors /// - /// * If an `owner`'s token query is out of bounds for `index`, - /// then the error [`Error::OutOfBoundsIndex`] is returned. + /// * [`Error::OutOfBoundsIndex`] - If an `owner`'s token query is out of + /// bounds for `index`, then the error is returned. + fn token_by_index(&self, index: U256) -> Result; } @@ -180,8 +181,8 @@ impl Erc721Enumerable { /// /// # Errors /// - /// If owner address is `Address::ZERO`, then the error - /// [`crate::token::erc721::Error::InvalidOwner`] is returned. + /// * [`crate::token::erc721::Error::InvalidOwner`] - If owner address is + /// `Address::ZERO`, then the error is returned. pub fn _add_token_to_owner_enumeration( &mut self, to: Address, @@ -231,8 +232,8 @@ impl Erc721Enumerable { /// /// # Errors /// - /// If owner address is `Address::ZERO`, then the error - /// [`crate::token::erc721::Error::InvalidOwner`] is returned. + /// * [`crate::token::erc721::Error::InvalidOwner`] - If owner address is + /// `Address::ZERO`, then the error is returned. pub fn _remove_token_from_owner_enumeration( &mut self, from: Address, @@ -326,8 +327,8 @@ impl Erc721Enumerable { /// /// # Errors /// - /// * If an `amount` is greater than `0`, then the error - /// [`Error::EnumerableForbiddenBatchMint`] is returned. + /// * [`Error::EnumerableForbiddenBatchMint`] - If an `amount` is greater + /// than `0`, then the error is returned. pub fn _check_increase_balance(amount: u128) -> Result<(), Error> { if amount > 0 { Err(ERC721EnumerableForbiddenBatchMint {}.into()) diff --git a/contracts/src/token/erc721/extensions/metadata.rs b/contracts/src/token/erc721/extensions/metadata.rs index cc417c674..1c4b3ca94 100644 --- a/contracts/src/token/erc721/extensions/metadata.rs +++ b/contracts/src/token/erc721/extensions/metadata.rs @@ -84,27 +84,29 @@ impl Erc721Metadata { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: In order to expose this function in the ABI, you need to annotate + /// it with `#[selector(name = "tokenURI")]` and ensure that the `erc721` + /// parameter is passed internally. This design works around Stylus's lack + /// of inheritance while avoiding code duplication. See the Example section. + /// /// # Arguments /// /// * `&self` - Read access to the contract's state. - /// * `token_id` - Id of a token. + /// * `token_id` - ID of a token. /// * `erc721` - Read access to a contract providing [`IErc721`] interface. /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// - /// NOTE: In order to have [`Erc721Metadata::token_uri`] exposed in ABI, - /// you need to do this manually. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// - /// # Examples + /// # Example /// /// ```rust,ignore /// #[selector(name = "tokenURI")] /// pub fn token_uri(&self, token_id: U256) -> Result> { /// Ok(self.metadata.token_uri(token_id, &self.erc721)?) /// } + /// ``` pub fn token_uri( &self, token_id: U256, diff --git a/contracts/src/token/erc721/extensions/uri_storage.rs b/contracts/src/token/erc721/extensions/uri_storage.rs index 96fdc33a4..aaf2f4c30 100644 --- a/contracts/src/token/erc721/extensions/uri_storage.rs +++ b/contracts/src/token/erc721/extensions/uri_storage.rs @@ -51,7 +51,7 @@ impl Erc721UriStorage { /// * `token_uri` - URI for the token. /// /// # Events - /// Emits a [`MetadataUpdate`] event. + /// * Emits a [`MetadataUpdate`] event. pub fn _set_token_uri(&mut self, token_id: U256, token_uri: String) { self._token_uris.setter(token_id).set_str(token_uri); evm::log(MetadataUpdate { token_id }); @@ -59,6 +59,10 @@ impl Erc721UriStorage { /// Returns the Uniform Resource Identifier (URI) for `token_id` token. /// + /// NOTE: In order to expose this function in the ABI, you need to annotate + /// it with `#[selector(name = "tokenURI")]` and ensure that the `erc721` + /// parameter is passed internally. This design works around Stylus's lack + /// of inheritance while avoiding code duplication. See the Example section. /// # Arguments /// /// * `&self` - Read access to the contract's state. @@ -68,11 +72,8 @@ impl Erc721UriStorage { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist. /// - /// NOTE: In order to have [`Erc721UriStorage::token_uri`] exposed in ABI, - /// you need to do this manually. /// /// # Examples /// diff --git a/contracts/src/token/erc721/mod.rs b/contracts/src/token/erc721/mod.rs index 21a9b0c4f..ecd29b42a 100644 --- a/contracts/src/token/erc721/mod.rs +++ b/contracts/src/token/erc721/mod.rs @@ -344,14 +344,14 @@ pub trait IErc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. - /// If the caller does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`, then + /// the error is returned. + /// * [`Error::InsufficientApproval`] - If the caller does not have the + /// right to approve, then the error is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. /// /// # Requirements: /// @@ -363,7 +363,7 @@ pub trait IErc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. fn transfer_from( &mut self, from: Address, @@ -385,11 +385,11 @@ pub trait IErc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `auth` (param of [`Erc721::_approve`]) does not have a right to - /// approve this token, then the error - /// [`Error::InvalidApprover`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. + /// * [`Error::InvalidApprover`] - If `auth` (param of [`Erc721::_approve`]) + /// does not have a right to approve this token, then the error is + /// returned. /// /// # Requirements: /// @@ -398,7 +398,7 @@ pub trait IErc721 { /// /// # Events /// - /// Emits an [`Approval`] event. + /// * Emits an [`Approval`] event. fn approve( &mut self, to: Address, @@ -420,8 +420,8 @@ pub trait IErc721 { /// /// # Errors /// - /// * If `operator` is `Address::ZERO`, then the error - /// [`Error::InvalidOperator`] is returned. + /// * [`Error::InvalidOperator`] - If `operator` is `Address::ZERO`, then + /// the error is returned. /// /// # Requirements: /// @@ -429,7 +429,7 @@ pub trait IErc721 { /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * Emits an [`ApprovalForAll`] event. fn set_approval_for_all( &mut self, operator: Address, @@ -445,8 +445,8 @@ pub trait IErc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. /// /// # Requirements: /// @@ -633,10 +633,10 @@ impl Erc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `spender` does not have the right to approve, then the error - /// [`Error::InsufficientApproval`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. + /// * [`Error::InsufficientApproval`] - If `spender` does not have the right + /// to approve, then the error is returned. pub fn _check_authorized( &self, owner: Address, @@ -696,15 +696,15 @@ impl Erc721 { /// /// # Errors /// - /// If token does not exist and `auth` is not `Address::ZERO`, then the - /// error [`Error::NonexistentToken`] is returned. - /// If `auth` is not `Address::ZERO` and `auth` does not have a right to - /// approve this token, then the error - /// [`Error::InsufficientApproval`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist and `auth` + /// is not `Address::ZERO`, then the error is returned. + /// * [`Error::InsufficientApproval`] - If `auth` is not `Address::ZERO` and + /// `auth` does not have a right to approve this token, then the error is + /// returned. /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _update( &mut self, to: Address, @@ -748,10 +748,10 @@ impl Erc721 { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidSender`] - If `token_id` already exists, then the + /// error is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. /// /// # Requirements: /// @@ -760,7 +760,7 @@ impl Erc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _mint(&mut self, to: Address, token_id: U256) -> Result<(), Error> { if to.is_zero() { return Err( @@ -791,13 +791,13 @@ impl Erc721 { /// /// # Errors /// - /// If `token_id` already exists, then the error - /// [`Error::InvalidSender`] is returned. - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidSender`] - If `token_id` already exists, then the + /// error is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its interface + /// id or returned with an error, then the error is returned. /// /// # Requirements: /// @@ -808,7 +808,7 @@ impl Erc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _safe_mint( &mut self, to: Address, @@ -838,8 +838,8 @@ impl Erc721 { /// /// # Errors /// - /// If token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. /// /// # Requirements: /// @@ -847,7 +847,7 @@ impl Erc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _burn(&mut self, token_id: U256) -> Result<(), Error> { let previous_owner = self._update(Address::ZERO, token_id, Address::ZERO)?; @@ -871,12 +871,12 @@ impl Erc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. + /// * [`Error::NonexistentToken`] - If `token_id` does not exist, then the + /// error is returned. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`, then + /// the error is returned. /// /// # Requirements: /// @@ -885,7 +885,7 @@ impl Erc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _transfer( &mut self, from: Address, @@ -935,12 +935,12 @@ impl Erc721 { /// /// # Errors /// - /// If `to` is `Address::ZERO`, then the error - /// [`Error::InvalidReceiver`] is returned. - /// If `token_id` does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If the previous owner is not `from`, then the error - /// [`Error::IncorrectOwner`] is returned. + /// * [`Error::InvalidReceiver`] - If `to` is `Address::ZERO`, then the + /// error is returned. + /// * [`Error::NonexistentToken`] - If `token_id` does not exist, then the + /// error is returned. + /// * [`Error::IncorrectOwner`] - If the previous owner is not `from`, then + /// the error is returned. /// /// # Requirements: /// @@ -953,7 +953,7 @@ impl Erc721 { /// /// # Events /// - /// Emits a [`Transfer`] event. + /// * Emits a [`Transfer`] event. pub fn _safe_transfer( &mut self, from: Address, @@ -981,14 +981,14 @@ impl Erc721 { /// /// # Errors /// - /// If the token does not exist, then the error - /// [`Error::NonexistentToken`] is returned. - /// If `auth` does not have a right to approve this token, then the error - /// [`Error::InvalidApprover`] is returned. + /// * [`Error::NonexistentToken`] - If the token does not exist, then the + /// error is returned. + /// * [`Error::InvalidApprover`] - If `auth` does not have a right to + /// approve this token, then the error is returned. /// /// # Events /// - /// Emits an [`Approval`] event. + /// * Emits an [`Approval`] event. pub fn _approve( &mut self, to: Address, @@ -1038,7 +1038,7 @@ impl Erc721 { /// /// # Events /// - /// Emits an [`ApprovalForAll`] event. + /// * Emits an [`ApprovalForAll`] event. pub fn _set_approval_for_all( &mut self, owner: Address, @@ -1099,9 +1099,9 @@ impl Erc721 { /// /// # Errors /// - /// If [`IERC721Receiver::on_erc_721_received`] hasn't returned its - /// interface id or returned with error, then the error - /// [`Error::InvalidReceiver`] is returned. + /// * [`Error::InvalidReceiver`] - If + /// [`IERC721Receiver::on_erc_721_received`] hasn't returned its interface + /// id or returned with error, then the error is returned. pub fn _check_on_erc721_received( &mut self, operator: Address, diff --git a/contracts/src/utils/cryptography/ecdsa.rs b/contracts/src/utils/cryptography/ecdsa.rs index 73d7d6152..3dae1c95e 100644 --- a/contracts/src/utils/cryptography/ecdsa.rs +++ b/contracts/src/utils/cryptography/ecdsa.rs @@ -85,10 +85,10 @@ impl MethodError for ecdsa::Error { /// /// # Errors /// -/// * If the `s` value is grater than [`SIGNATURE_S_UPPER_BOUND`], then the -/// error [`Error::InvalidSignatureS`] is returned. -/// * If the recovered address is `Address::ZERO`, then the error -/// [`Error::InvalidSignature`] is returned. +/// * [`Error::InvalidSignatureS`] - If the `s` value is grater than +/// [`SIGNATURE_S_UPPER_BOUND`], then the error is returned. +/// * [`Error::InvalidSignature`] - If the recovered address is `Address::ZERO`, +/// then the error is returned. /// /// # Panics /// @@ -120,8 +120,8 @@ pub fn recover( /// /// # Errors /// -/// * If the recovered address is `Address::ZERO`, then the error -/// [`Error::InvalidSignature`] is returned. +/// * [`Error::InvalidSignature`] - If the recovered address is `Address::ZERO`, +/// then the error is returned. /// /// # Panics /// @@ -194,8 +194,8 @@ fn encode_calldata(hash: B256, v: u8, r: B256, s: B256) -> Vec { /// /// # Errors /// -/// * If the `s` value is grater than [`SIGNATURE_S_UPPER_BOUND`], then the -/// error [`Error::InvalidSignatureS`] is returned. +/// * [`Error::InvalidSignatureS`] - If the `s` value is grater than +/// [`SIGNATURE_S_UPPER_BOUND`], then the error is returned. /// /// [Ethereum Yellow paper]: https://ethereum.github.io/yellowpaper/paper.pdf fn check_if_malleable(s: &B256) -> Result<(), Error> { diff --git a/contracts/src/utils/nonces.rs b/contracts/src/utils/nonces.rs index 4a588af5f..353f04733 100644 --- a/contracts/src/utils/nonces.rs +++ b/contracts/src/utils/nonces.rs @@ -67,7 +67,7 @@ impl Nonces { /// /// # Panics /// - /// If the nonce for the given `owner` exceeds `U256::MAX`. + /// * If the nonce for the given `owner` exceeds `U256::MAX`. pub fn use_nonce(&mut self, owner: Address) -> U256 { let nonce = self._nonces.get(owner); @@ -89,12 +89,12 @@ impl Nonces { /// /// # Errors /// - /// Returns an error if the `nonce` is not the next valid nonce for the - /// owner. + /// * [`Error::InvalidAccountNonce`] - Returns an error if the `nonce` is + /// not the next valid nonce for the owner. /// /// # Panics /// - /// If the nonce for the given `owner` exceeds `U256::MAX`. + /// * If the nonce for the given `owner` exceeds `U256::MAX`. pub fn use_checked_nonce( &mut self, owner: Address, diff --git a/contracts/src/utils/pausable.rs b/contracts/src/utils/pausable.rs index 60e369628..93e2469d4 100644 --- a/contracts/src/utils/pausable.rs +++ b/contracts/src/utils/pausable.rs @@ -110,8 +110,8 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in `Unpaused` state, then the error - /// [`Error::ExpectedPause`] is returned. + /// * [`Error::ExpectedPause`] - If the contract is in `Unpaused` state, + /// then the error is returned. pub fn unpause(&mut self) -> Result<(), Error> { self.when_paused()?; self._paused.set(false); @@ -128,8 +128,8 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in the `Paused` state, then the error - /// [`Error::EnforcedPause`] is returned. + /// * [`Error::EnforcedPause`] - If the contract is in the `Paused` state, + /// then the error is returned. pub fn when_not_paused(&self) -> Result<(), Error> { if self._paused.get() { return Err(Error::EnforcedPause(EnforcedPause {})); @@ -146,8 +146,8 @@ impl Pausable { /// /// # Errors /// - /// If the contract is in `Unpaused` state, then the error - /// [`Error::ExpectedPause`] is returned. + /// * [`Error::ExpectedPause`] - If the contract is in `Unpaused` state, + /// then the error is returned. pub fn when_paused(&self) -> Result<(), Error> { if !self._paused.get() { return Err(Error::ExpectedPause(ExpectedPause {})); diff --git a/contracts/src/utils/reentrant_call_handler.rs b/contracts/src/utils/reentrant_call_handler.rs index f32de8e34..9303fad5e 100644 --- a/contracts/src/utils/reentrant_call_handler.rs +++ b/contracts/src/utils/reentrant_call_handler.rs @@ -69,8 +69,8 @@ pub trait ReentrantCallHandler { /// /// # Errors /// - /// * Returns [`stylus_sdk::ArbResult`] indicating the success or failure of - /// the call. + /// * [`Error::ExpectedPause`] - Returns this indicating the success or + /// failure of the call. fn call_with_reentrant_handling( self, token: Address,