docs: normalize struct docs

contracts/src/access/control.rs

@@ -105,7 +105,9 @@ pub enum Error {
     BadConfirmation(AccessControlBadConfirmation),
 }
 
-/// Information about a specific role.
+/// State of a [`RoleData`] contract.
+///
+/// Stores information about a specific role.
 #[storage]
 pub struct RoleData {
     /// Whether an account is member of a certain role.
@@ -114,7 +116,7 @@ pub struct RoleData {
     pub admin_role: StorageFixedBytes<32>,
 }
 
-/// State of an `AccessControl` contract.
+/// State of an [`AccessControl`] contract.
 #[storage]
 pub struct AccessControl {
     /// Role identifier -> Role information.

contracts/src/access/ownable.rs

@@ -65,7 +65,7 @@ impl MethodError for Error {
     }
 }
 
-/// State of an `Ownable` contract.
+/// State of an [`Ownable`] contract.
 #[storage]
 pub struct Ownable {
     /// The current owner of this contract.

contracts/src/access/ownable_two_step.rs

@@ -57,7 +57,7 @@ pub enum Error {
     Ownable(OwnableError),
 }
 
-/// State of an `Ownable2Step` contract.
+/// State of an [`Ownable2Step`] contract.
 #[storage]
 pub struct Ownable2Step {
     /// [`Ownable`] contract.

contracts/src/finance/vesting_wallet.rs

@@ -95,7 +95,7 @@ pub enum Error {
     InvalidToken(InvalidToken),
 }
 
-/// State of the [`VestingWallet`] Contract.
+/// State of a [`VestingWallet`] Contract.
 #[storage]
 pub struct VestingWallet {
     /// [`Ownable`] contract.

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

@@ -31,7 +31,7 @@ mod sol {
     }
 }
 
-/// URI Metadata of an [`crate::token::erc1155::Erc1155`] token.
+/// State of an [`Erc1155MetadataUri`] contract.
 #[storage]
 pub struct Erc1155MetadataUri {
     /// Used as the URI for all token types by relying on ID substitution,

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

@@ -27,10 +27,10 @@ use crate::{
     utils::math::storage::{AddAssignChecked, SubAssignUnchecked},
 };
 
-/// State of an [`Erc1155Supply`] token.
+/// State of an [`Erc1155Supply`] contract.
 #[storage]
 pub struct Erc1155Supply {
-    /// ERC-1155 contract storage.
+    /// [`Erc1155`] contract.
     pub erc1155: Erc1155,
     /// Mapping from token id to total supply.
     #[allow(clippy::used_underscore_binding)]

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

@@ -12,7 +12,7 @@ use stylus_sdk::{
 
 use super::metadata_uri::{IErc1155MetadataUri, URI};
 
-/// Uri Storage.
+/// State of an [`Erc1155UriStorage`] contract.
 #[storage]
 pub struct Erc1155UriStorage {
     /// Optional base URI.

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

@@ -45,7 +45,7 @@ pub enum Error {
     InvalidCap(ERC20InvalidCap),
 }
 
-/// State of a Capped Contract.
+/// State of a [`Capped`] Contract.
 #[storage]
 pub struct Capped {
     /// A cap to the supply of tokens.

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

@@ -113,7 +113,7 @@ mod borrower {
     }
 }
 
-/// State of the [`Erc20FlashMint`] Contract.
+/// State of an [`Erc20FlashMint`] Contract.
 #[storage]
 pub struct Erc20FlashMint {
     /// Fee applied when doing flash loans.

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

@@ -15,12 +15,10 @@ use alloc::vec::Vec;
 
 use crate::utils::Metadata;
 
-/// Metadata of the [`super::super::Erc20`] token.
-///
-/// It has hardcoded `decimals` to [`DEFAULT_DECIMALS`].
+/// State of an [`Erc20Metadata`] contract.
 #[storage]
 pub struct Erc20Metadata {
-    /// Common Metadata.
+    /// [`Metadata`] contract.
     #[allow(clippy::used_underscore_binding)]
     pub _metadata: Metadata,
 }

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

@@ -73,14 +73,14 @@ pub enum Error {
     ECDSA(ecdsa::Error),
 }
 
-/// State of a Permit Contract.
+/// State of an [`Erc20Permit`] Contract.
 #[storage]
 pub struct Erc20Permit<T: IEip712 + StorageType> {
-    /// ERC-20 contract.
+    /// [`Erc20`] contract.
     pub erc20: Erc20,
-    /// Nonces contract.
+    /// [`Nonces`] contract.
     pub nonces: Nonces,
-    /// EIP-712 contract. Must implement [`IEip712`] trait.
+    /// Contract implementing [`IEip712`] trait.
     pub eip712: T,
 }
 

contracts/src/token/erc20/mod.rs

@@ -124,7 +124,7 @@ impl MethodError for Error {
     }
 }
 
-/// State of an `Erc20` token.
+/// State of an [`Erc20`] token.
 #[storage]
 pub struct Erc20 {
     /// Maps users to balances.

contracts/src/token/erc20/utils/safe_erc20.rs

@@ -85,7 +85,7 @@ mod token {
     }
 }
 
-/// State of the [`SafeErc20`] Contract.
+/// State of a [`SafeErc20`] Contract.
 #[storage]
 pub struct SafeErc20 {}
 

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

@@ -56,12 +56,12 @@ type StorageU96 = <S160 as Size>::KeyStorage;
 /// State of an [`Erc721Consecutive`] token.
 #[storage]
 pub struct Erc721Consecutive {
-    /// Erc721 contract storage.
+    /// [`Erc721`] contract.
     pub erc721: Erc721,
-    /// Checkpoint library contract for sequential ownership.
+    /// [`Trace`] contract for sequential ownership.
     #[allow(clippy::used_underscore_binding)]
     pub _sequential_ownership: Trace<S160>,
-    /// BitMap library contract for sequential burn of tokens.
+    /// [`BitMap`] contract for sequential burn of tokens.
     #[allow(clippy::used_underscore_binding)]
     pub _sequential_burn: BitMap,
     /// Used to offset the first token id in `next_consecutive_id` calculation.

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

@@ -60,7 +60,7 @@ pub enum Error {
     EnumerableForbiddenBatchMint(ERC721EnumerableForbiddenBatchMint),
 }
 
-/// State of an Enumerable extension.
+/// State of an [`Erc721Enumerable`] contract.
 #[storage]
 pub struct Erc721Enumerable {
     /// Maps owners to a mapping of indices to tokens ids.

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

@@ -16,10 +16,10 @@ use crate::{
     utils::{introspection::erc165::IErc165, Metadata},
 };
 
-/// Metadata of an [`crate::token::erc721::Erc721`] token.
+/// State of an [`Erc721Metadata`] contract.
 #[storage]
 pub struct Erc721Metadata {
-    /// Common Metadata.
+    /// [`Metadata`] contract.
     #[allow(clippy::used_underscore_binding)]
     pub _metadata: Metadata,
     /// Base URI for tokens.

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

@@ -33,7 +33,7 @@ mod sol {
     }
 }
 
-/// Uri Storage.
+/// State of an [`Erc721UriStorage`] contract.
 #[storage]
 pub struct Erc721UriStorage {
     /// Optional mapping for token URIs.

contracts/src/utils/metadata.rs

@@ -5,7 +5,7 @@ use stylus_sdk::{
     prelude::storage, storage::StorageString, stylus_proc::public,
 };
 
-/// Metadata of the token.
+/// State of a [`Metadata`] contract.
 #[storage]
 pub struct Metadata {
     /// Token name.

contracts/src/utils/nonces.rs

@@ -35,7 +35,7 @@ pub enum Error {
     InvalidAccountNonce(InvalidAccountNonce),
 }
 
-/// State of a Nonces Contract.
+/// State of a [`Nonces`] Contract.
 #[storage]
 pub struct Nonces {
     /// Mapping from address to its nonce.

contracts/src/utils/pausable.rs

@@ -64,7 +64,7 @@ pub enum Error {
     ExpectedPause(ExpectedPause),
 }
 
-/// State of a Pausable Contract.
+/// State of a [`Pausable`] Contract.
 #[storage]
 pub struct Pausable {
     /// Indicates whether the contract is `Paused`.

contracts/src/utils/structs/bitmap.rs

@@ -22,7 +22,7 @@ use stylus_sdk::{
 const ONE: U256 = uint!(0x1_U256);
 const HEX_FF: U256 = uint!(0xff_U256);
 
-/// State of bit map.
+/// State of a [`BitMap`] contract.
 #[storage]
 pub struct BitMap {
     /// Inner laying mapping.

contracts/src/utils/structs/checkpoints/mod.rs

@@ -47,15 +47,15 @@ impl MethodError for Error {
     }
 }
 
-/// State of the checkpoint library contract.
+/// State of a [`Trace`] contract.
 #[storage]
 pub struct Trace<S: Size> {
     /// Stores checkpoints in a dynamic array sorted by key.
     #[allow(clippy::used_underscore_binding)]
     pub _checkpoints: StorageVec<Checkpoint<S>>,
 }
 
-/// State of a single checkpoint.
+/// State of a [`Checkpoint`] contract.
 #[storage]
 pub struct Checkpoint<S: Size> {
     /// The key of the checkpoint. Used as a sorting key.

lib/crypto/src/arithmetic/uint.rs

@@ -27,7 +27,7 @@ use crate::{
 
 /// Stack-allocated big unsigned integer.
 ///
-/// Generic over number [`N`] of [`Limb`]s.
+/// Generic over number `N` of [`Limb`]s.
 #[derive(Copy, Clone, PartialEq, Eq, Hash, Zeroize)]
 pub struct Uint<const N: usize> {
     pub(crate) limbs: Limbs<N>,