Apply suggestions from code review (ref: OpenZeppelin#476)

Co-authored-by: Nenad <[email protected]>

contracts/src/access/control.rs

@@ -187,7 +187,7 @@ impl AccessControl {
     ///
     /// # Events
     ///
-    /// * [`RoleGranted`].
+    /// * [`RoleGranted`]
     pub fn grant_role(
         &mut self,
         role: B256,

contracts/src/token/erc1155/extensions/supply.rs

@@ -216,8 +216,8 @@ impl Erc1155Supply {
     ///
     /// # Events
     ///
-    /// * [`erc1155::TransferSingle`] - if the arrays contain one element.
-    /// * [`erc1155::TransferBatch`] - if the arrays contain more than one
+    /// * [`erc1155::TransferSingle`] - If the arrays contain one element.
+    /// * [`erc1155::TransferBatch`] - If the arrays contain more than one
     ///   element.
     ///
     /// # Panics

contracts/src/token/erc1155/extensions/uri_storage.rs

@@ -26,8 +26,11 @@ 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.
+    /// NOTE: To expose this function in your contract's ABI, implement it as
+    /// shown in the Examples section below, accepting only the `token_id`
+    /// parameter. The `metadata_uri` reference should come from your contract's
+    /// state. The implementation should forward the call to your internal
+    /// storage instance along with the metadata reference.
     ///
     /// # Arguments
     ///

contracts/src/token/erc20/extensions/burnable.rs

@@ -28,7 +28,7 @@ pub trait IErc20Burnable {
     ///
     /// # Events
     ///
-    /// * [`super::super::Transfer`].
+    /// * [`erc20::Transfer`].
     fn burn(&mut self, value: U256) -> Result<(), Self::Error>;
 
     /// Destroys a `value` amount of tokens from `account`, lowering the total
@@ -45,7 +45,7 @@ pub trait IErc20Burnable {
     ///
     /// * [`Error::InsufficientAllowance`] - If not enough allowance is
     ///   available.
-    /// * [`Error::InvalidSender`]  - If the `from` address is `Address::ZERO`.
+    /// * [`Error::InvalidSender`] - If the `from` address is `Address::ZERO`.
     /// * [`Error::InsufficientBalance`] - If the `from` address doesn't have
     ///   enough tokens.
     ///

contracts/src/token/erc20/extensions/permit.rs

@@ -121,9 +121,9 @@ impl<T: IEip712 + StorageType> Erc20Permit<T> {
     ///
     /// * `spender` cannot be the ``Address::ZERO``.
     /// * `deadline` must be a timestamp in the future.
-    /// * `v`, `r` and `s` must be a valid secp256k1 signature from `owner`
-    /// over the EIP712-formatted function arguments.
-    /// * the signature must use `owner`'s current nonce.
+    /// * `v`, `r` and `s` must be a valid secp256k1 signature from `owner` over
+    ///   the EIP712-formatted function arguments.
+    /// * The signature must use `owner`'s current nonce.
     ///
     /// # Arguments
     ///
@@ -151,7 +151,7 @@ impl<T: IEip712 + StorageType> Erc20Permit<T> {
     ///
     /// # Events
     ///
-    /// * [`crate::token::erc20::Approval`].
+    /// * [`erc20::Approval`].
     #[allow(clippy::too_many_arguments)]
     pub fn permit(
         &mut self,
@@ -314,7 +314,7 @@ impl<T: IEip712 + StorageType> Erc20Permit<T> {
     ///
     /// # Events
     ///
-    /// * * [`crate::token::erc20::Transfer`].
+    /// * [`erc20::Transfer`].
     pub fn transfer_from(
         &mut self,
         from: Address,

contracts/src/token/erc721/extensions/burnable.rs

@@ -32,7 +32,7 @@ pub trait IErc721Burnable {
     ///
     /// # Events
     ///
-    /// * [`super::super::Transfer`].
+    /// * [`erc721::Transfer`].
     fn burn(&mut self, token_id: U256) -> Result<(), Self::Error>;
 }
 

contracts/src/token/erc721/extensions/consecutive.rs

@@ -278,9 +278,9 @@ impl Erc721Consecutive {
     /// `batch_size` is 0, returns the number of consecutive ids minted so
     /// far.
     ///
-    /// CAUTION: Does not emit a [Transfer] event. This is ERC-721 compliant as
-    /// long as it is done inside of the constructor, which is enforced by this
-    /// function.
+    /// CAUTION: Does not emit a [`Transfer`] event. This is ERC-721 compliant
+    /// as long as it is done inside of the constructor, which is enforced by
+    /// this function.
     ///
     /// CAUTION: Does not invoke
     /// [`erc721::IERC721Receiver::on_erc_721_received`] on the receiver.
@@ -782,7 +782,7 @@ impl Erc721Consecutive {
     ///
     /// Overrides to ownership logic should be done to
     /// [`Self::_owner_of`].
-    //
+    ///
     /// # Arguments
     ///
     /// * `&self` - Read access to the contract's state.

contracts/src/token/erc721/extensions/enumerable.rs

@@ -183,8 +183,7 @@ impl Erc721Enumerable {
     ///
     /// # Errors
     ///
-    /// * [`crate::token::erc721::Error::InvalidOwner`] - If owner address is
-    ///   `Address::ZERO`.
+    /// * [`erc721::Error::InvalidOwner`] - If owner address is `Address::ZERO`.
     pub fn _add_token_to_owner_enumeration(
         &mut self,
         to: Address,

contracts/src/token/erc721/extensions/metadata.rs

@@ -84,10 +84,13 @@ 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.
+    /// NOTE: To expose this function in your contract's ABI, implement it as
+    /// shown in the Examples section below, accepting only the `token_id`
+    /// parameter. The `erc721` reference should come from your contract's
+    /// state. The implementation should use `#[selector(name = "tokenURI")]` to
+    /// match Solidity's camelCase naming convention and it should forward the
+    /// call to your internal storage instance along with the `erc721`
+    /// reference.
     ///
     /// # Arguments
     ///

contracts/src/token/erc721/extensions/uri_storage.rs

@@ -60,10 +60,13 @@ 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.
+    /// NOTE: To expose this function in your contract's ABI, implement it as
+    /// shown in the Examples section below, accepting only the `token_id`
+    /// parameter. Both the `erc721` and `metadata` references should come from
+    /// your contract's state. The implementation should use
+    /// `#[selector(name = "tokenURI")]` to match Solidity's camelCase naming
+    /// convention and it should forward the call to your internal storage
+    /// instance along with both references.
     ///
     /// # Arguments
     ///

contracts/src/utils/cryptography/ecdsa.rs

@@ -193,7 +193,7 @@ fn encode_calldata(hash: B256, v: u8, r: B256, s: B256) -> Vec<u8> {
 ///
 /// # Errors
 ///
-/// * [`Error::InvalidSignatureS`] - If the `s` value is grater than
+/// * [`Error::InvalidSignatureS`] - If the `s` value is greater than
 ///   [`SIGNATURE_S_UPPER_BOUND`].
 ///
 /// [Ethereum Yellow paper]: https://ethereum.github.io/yellowpaper/paper.pdf

contracts/src/utils/introspection/erc165.rs

@@ -16,16 +16,15 @@ use openzeppelin_stylus_proc::interface_id;
 #[interface_id]
 pub trait IErc165 {
     /// Returns true if this contract implements the interface defined by
-    /// `interface_id`. See the corresponding [ERC section] to learn more about
-    /// how these ids are created.
+    /// `interface_id`. See the corresponding [ERC] to learn more about how
+    /// these ids are created.
     ///
     /// NOTE: Method [`IErc165::supports_interface`] should be reexported with
     /// `#[public]` macro manually, see the Example section.
     ///
     /// # Arguments
     ///
-    /// * `interface_id` - The interface identifier, as specified in [ERC
-    ///   section].
+    /// * `interface_id` - The interface identifier, as specified in the [ERC].
     ///
     /// # Example
     ///
@@ -39,7 +38,7 @@ pub trait IErc165 {
     /// }
     /// ```
     ///
-    /// [ERC section]: https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified
+    /// [ERC]: https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified
     fn supports_interface(interface_id: FixedBytes<4>) -> bool;
 }