docs: make Rust docs consistent

contracts/src/access/control.rs

@@ -145,8 +145,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`.
     pub fn only_role(&self, role: B256) -> Result<(), Error> {
         self._check_role(role, msg::sender())
     }
@@ -170,7 +170,7 @@ impl AccessControl {
     /// If `account` had not been already granted `role`, emits a
     /// [`RoleGranted`] event.
     ///
-    /// # Requirements:
+    /// # Requirements
     ///
     /// * The caller must have `role`'s admin role.
     ///
@@ -182,12 +182,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`.
     ///
     /// # Events
     ///
-    /// May emit a [`RoleGranted`] event.
+    /// * [`RoleGranted`].
     pub fn grant_role(
         &mut self,
         role: B256,
@@ -203,7 +203,7 @@ impl AccessControl {
     ///
     /// If `account` had been granted `role`, emits a [`RoleRevoked`] event.
     ///
-    /// # Requirements:
+    /// # Requirements
     ///
     /// * The caller must have `role`'s admin role.
     ///
@@ -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`.
     ///
     /// # Events
     ///
-    /// May emit a [`RoleRevoked`] event.
+    /// * [`RoleRevoked`].
     pub fn revoke_role(
         &mut self,
         role: B256,
@@ -239,7 +239,7 @@ impl AccessControl {
     /// for accounts to lose their privileges if they are compromised (such as
     /// when a trusted device is misplaced).
     ///
-    /// # Requirements:
+    /// # Requirements
     ///
     /// * The caller must be `confirmation`.
     ///
@@ -251,13 +251,12 @@ 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.
     ///
     /// # Events
     ///
-    /// If the calling account has its `role` revoked, emits a [`RoleRevoked`]
-    /// event.
+    /// * [`RoleRevoked`] - If the calling account has its `role` revoked.
     pub fn renounce_role(
         &mut self,
         role: B256,
@@ -288,7 +287,7 @@ impl AccessControl {
     ///
     /// # Events
     ///
-    /// Emits a [`RoleAdminChanged`] event.
+    /// * [`RoleAdminChanged`].
     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 +308,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`.
     pub fn _check_role(
         &self,
         role: B256,
@@ -338,7 +337,7 @@ impl AccessControl {
     ///
     /// # Events
     ///
-    /// May emit a [`RoleGranted`] event.
+    /// * [`RoleGranted`].
     pub fn _grant_role(&mut self, role: B256, account: Address) -> bool {
         if self.has_role(role, account) {
             false
@@ -362,7 +361,7 @@ impl AccessControl {
     ///
     /// # Events
     ///
-    /// May emit a [`RoleRevoked`] event.
+    /// * [`RoleRevoked`].
     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);

contracts/src/access/ownable.rs

@@ -96,12 +96,11 @@ pub trait IOwnable {
     ///
     /// # Errors
     ///
-    /// If `new_owner` is the zero address, then the error
-    /// [`OwnableInvalidOwner`] is returned.
+    /// * [`OwnableInvalidOwner`] - If `new_owner` is the `Address::ZERO`.
     ///
     /// # Events
     ///
-    /// Emits a [`OwnershipTransferred`] event.
+    /// * [`OwnershipTransferred`].
     fn transfer_ownership(
         &mut self,
         new_owner: Address,
@@ -120,12 +119,11 @@ 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.
     ///
     /// # Events
     ///
-    /// Emits a [`OwnershipTransferred`] event.
+    /// * [`OwnershipTransferred`].
     fn renounce_ownership(&mut self) -> Result<(), Self::Error>;
 }
 
@@ -170,8 +168,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.
     pub fn only_owner(&self) -> Result<(), Error> {
         let account = msg::sender();
         if self.owner() != account {
@@ -193,7 +191,7 @@ impl Ownable {
     ///
     /// # Events
     ///
-    /// Emits a [`OwnershipTransferred`] event.
+    /// * [`OwnershipTransferred`].
     pub fn _transfer_ownership(&mut self, new_owner: Address) {
         let previous_owner = self._owner.get();
         self._owner.set(new_owner);

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.
     ///
     /// # Events
     ///
-    /// Emits a [`OwnershipTransferStarted`] event.
+    /// * [`OwnershipTransferStarted`].
     fn transfer_ownership(
         &mut self,
         new_owner: Address,
@@ -123,12 +123,12 @@ 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.
     ///
     /// # Events
     ///
-    /// Emits a [`crate::access::ownable::OwnershipTransferred`] event.
+    /// * [`crate::access::ownable::OwnershipTransferred`].
     fn accept_ownership(&mut self) -> Result<(), Self::Error>;
 
     /// Leaves the contract without owner. It will not be possible to call
@@ -139,14 +139,16 @@ pub trait IOwnable2Step {
     /// thereby disabling any functionality that is only available to the owner.
     ///
     /// # Arguments
+    ///
+    /// * `&mut self` - Write access to the contract's state.
+    ///
     /// # Errors
     ///
-    /// If not called by the owner, then the error
-    /// [`OwnableError::UnauthorizedAccount`] is returned.
+    /// * [`OwnableError::UnauthorizedAccount`] - If not called by the owner.
     ///
     /// # Events
     ///
-    /// Emits a [`crate::access::ownable::OwnershipTransferred`] event.
+    /// * [`crate::access::ownable::OwnershipTransferred`].
     fn renounce_ownership(&mut self) -> Result<(), Self::Error>;
 }
 
@@ -212,7 +214,7 @@ impl Ownable2Step {
     ///
     /// # Events
     ///
-    /// Emits a [`crate::access::ownable::OwnershipTransferred`] event.
+    /// * [`crate::access::ownable::OwnershipTransferred`].
     fn _transfer_ownership(&mut self, new_owner: Address) {
         self._pending_owner.set(Address::ZERO);
         self._ownable._transfer_ownership(new_owner);

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.
+    /// * [`ownable::Error::InvalidOwner`] - If `new_owner` is the
+    ///   `Address::ZERO`.
     ///
     /// # Events
     ///
-    /// Emits an [`ownable::OwnershipTransferred`] event.
+    /// * [`ownable::OwnershipTransferred`].
     fn transfer_ownership(
         &mut self,
         new_owner: Address,
@@ -190,12 +190,11 @@ 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.
     ///
     /// # Events
     ///
-    /// Emits an [`ownable::OwnershipTransferred`] event.
+    /// * [`ownable::OwnershipTransferred`].
     fn renounce_ownership(&mut self) -> Result<(), Self::Error>;
 
     /// The contract should be able to receive Ether.
@@ -251,8 +250,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 +265,12 @@ 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.
     ///
     /// # 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<U256, Self::Error>;
@@ -285,17 +283,16 @@ pub trait IVestingWallet {
     ///
     /// # Errors
     ///
-    /// If Ether transfer fails, then the error [`Error::ReleaseEtherFailed`] is
-    /// returned.
+    /// * [`Error::ReleaseEtherFailed`] - If Ether transfer fails.
     ///
     /// # Events
     ///
-    /// Emits an [`EtherReleased`] event.
+    /// * [`EtherReleased`].
     ///
     /// # 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 +305,18 @@ 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.
+    /// * [`safe_erc20::Error::SafeErc20FailedOperation`] - If the contract
+    ///   fails to execute the call.
     ///
     /// # Events
     ///
-    /// Emits an [`ERC20Released`] event.
+    /// * [`ERC20Released`].
     ///
     /// # 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 +330,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 +346,12 @@ 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.
     ///
     /// # 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,
@@ -505,7 +500,7 @@ impl VestingWallet {
     ///
     /// # Panics
     ///
-    /// If scaled, total allocation (mid calculation) exceeds `U256::MAX`.
+    /// * If scaled, total allocation (mid calculation) exceeds `U256::MAX`.
     fn vesting_schedule(&self, total_allocation: U256, timestamp: U64) -> U256 {
         let timestamp = U256::from(timestamp);