fix: natspec docs

contracts/interchain-token/InterchainToken.sol

@@ -15,18 +15,19 @@ abstract contract InterchainToken is IInterchainToken, ERC20 {
     /**
      * @notice Getter for the tokenManager used for this token.
      * @dev Needs to be overwritten.
-     * @return tokenManager_ the TokenManager called to facilitate cross chain transfers.
+     * @return tokenManager_ The TokenManager called to facilitate cross chain transfers.
      */
     function tokenManager() public view virtual returns (ITokenManager tokenManager_);
 
     /**
      * @notice Implementation of the interchainTransfer method
-     * @dev We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer.
-     * A different implementation could have `metadata` that tells this function which function to use or that it is used for anything else as well.
+     * @dev We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer.
+     * A different implementation could use metadata to specify a function to invoke, or for other purposes as well.
      * @param destinationChain The destination chain identifier.
      * @param recipient The bytes representation of the address of the recipient.
      * @param amount The amount of token to be transferred.
-     * @param metadata Either empty, to just facilitate an interchain transfer, or the data can be passed for an interchain contract call with transfer as per semantics defined by the token service.
+     * @param metadata Either empty, just to facilitate an interchain transfer, or the data to be passed for an interchain contract call with transfer
+     * as per semantics defined by the token service.
      */
     function interchainTransfer(
         string calldata destinationChain,
@@ -45,12 +46,12 @@ abstract contract InterchainToken is IInterchainToken, ERC20 {
     /**
      * @notice Implementation of the interchainTransferFrom method
      * @dev We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer.
-     * A different implementation could have `metadata` that tells this function which function to use or that it is used for anything else as well.
-     * @param sender the sender of the tokens. They need to have approved `msg.sender` before this is called.
-     * @param destinationChain the string representation of the destination chain.
-     * @param recipient the bytes representation of the address of the recipient.
-     * @param amount the amount of token to be transferred.
-     * @param metadata either empty, to just facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
+     * A different implementation could use metadata to specify a function to invoke, or for other purposes as well.
+     * @param sender The sender of the tokens. They need to have approved `msg.sender` before this is called.
+     * @param destinationChain The string representation of the destination chain.
+     * @param recipient The bytes representation of the address of the recipient.
+     * @param amount The amount of token to be transferred.
+     * @param metadata Either empty, just to facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
      */
     function interchainTransferFrom(
         address sender,
@@ -72,12 +73,13 @@ abstract contract InterchainToken is IInterchainToken, ERC20 {
     }
 
     /**
-     * @notice A method to be overwritten that will be called before an interchain transfer. You can approve the tokenManager here if you need and want to, to allow users for a 1-call transfer in case of a lock-unlock token manager.
-     * @param from the sender of the tokens. They need to have approved `msg.sender` before this is called.
-     * @param destinationChain the string representation of the destination chain.
-     * @param destinationAddress the bytes representation of the address of the recipient.
-     * @param amount the amount of token to be transferred.
-     * @param metadata either empty, to just facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
+     * @notice A method to be overwritten that will be called before an interchain transfer. One can approve the tokenManager here if needed,
+     * to allow users for a 1-call transfer in case of a lock-unlock token manager.
+     * @param from The sender of the tokens. They need to have approved `msg.sender` before this is called.
+     * @param destinationChain The string representation of the destination chain.
+     * @param destinationAddress The bytes representation of the address of the recipient.
+     * @param amount The amount of token to be transferred.
+     * @param metadata Either empty, just to facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
      */
     function _beforeInterchainTransfer(
         address from,

contracts/interfaces/IDistributable.sol

@@ -4,24 +4,29 @@ pragma solidity ^0.8.0;
 
 import { IRolesBase } from '@axelar-network/axelar-gmp-sdk-solidity/contracts/interfaces/IRolesBase.sol';
 
+/**
+ * @title IDistributable Interface
+ * @notice An interface for a contract module which provides a basic access control mechanism, where
+ * there is an account (a distributor) that can be granted exclusive access to specific functions.
+ */
 interface IDistributable is IRolesBase {
     /**
-     * @notice Change the distributor of the contract
-     * @dev Can only be called by the current distributor
-     * @param distributor_ The address of the new distributor
+     * @notice Change the distributor of the contract.
+     * @dev Can only be called by the current distributor.
+     * @param distributor_ The address of the new distributor.
      */
     function transferDistributorship(address distributor_) external;
 
     /**
-     * @notice Proposed a change of the distributor of the contract
-     * @dev Can only be called by the current distributor
-     * @param distributor_ The address of the new distributor
+     * @notice Proposed a change of the distributor of the contract.
+     * @dev Can only be called by the current distributor.
+     * @param distributor_ The address of the new distributor.
      */
     function proposeDistributorship(address distributor_) external;
 
     /**
-     * @notice Accept a change of the distributor of the contract
-     * @dev Can only be called by the proposed distributor
+     * @notice Accept a change of the distributor of the contract.
+     * @dev Can only be called by the proposed distributor.
      */
     function acceptDistributorship(address fromDistributor) external;
 

contracts/interfaces/IERC20BurnableFrom.sol

@@ -7,11 +7,11 @@ pragma solidity ^0.8.0;
  */
 interface IERC20BurnableFrom {
     /**
-     * @notice Function to burn tokens
-     * @notice Requires the caller to have allowance for `amount` on `from`
-     * @dev Can only be called by the distributor address.
-     * @param from The address that will have its tokens burnt
-     * @param amount The amount of tokens to burn
+     * @notice Function to burn tokens.
+     * @dev Requires the caller to have allowance for `amount` on `from`.
+     * Can only be called by the distributor address.
+     * @param from The address that will have its tokens burnt.
+     * @param amount The amount of tokens to burn.
      */
     function burnFrom(address from, uint256 amount) external;
 }

contracts/interfaces/IERC20MintableBurnable.sol

@@ -7,18 +7,18 @@ pragma solidity ^0.8.0;
  */
 interface IERC20MintableBurnable {
     /**
-     * @notice Function to mint new tokens
+     * @notice Function to mint new tokens.
      * @dev Can only be called by the distributor address.
-     * @param to The address that will receive the minted tokens
-     * @param amount The amount of tokens to mint
+     * @param to The address that will receive the minted tokens.
+     * @param amount The amount of tokens to mint.
      */
     function mint(address to, uint256 amount) external;
 
     /**
-     * @notice Function to burn tokens
+     * @notice Function to burn tokens.
      * @dev Can only be called by the distributor address.
-     * @param from The address that will have its tokens burnt
-     * @param amount The amount of tokens to burn
+     * @param from The address that will have its tokens burnt.
+     * @param amount The amount of tokens to burn.
      */
     function burn(address from, uint256 amount) external;
 }

contracts/interfaces/IERC20Named.sol

@@ -9,17 +9,20 @@ import { IERC20 } from '@axelar-network/axelar-gmp-sdk-solidity/contracts/interf
  */
 interface IERC20Named is IERC20 {
     /**
-     * @notice Getter for the name of the token
+     * @notice Getter for the name of the token.
+     * @return string Name of the token.
      */
     function name() external returns (string memory);
 
     /**
-     * @notice Getter for the symbol of the token
+     * @notice Getter for the symbol of the token.
+     * @return string The symbol of the token.
      */
     function symbol() external returns (string memory);
 
     /**
-     * @notice Getter for the decimals of the token
+     * @notice Getter for the decimals of the token.
+     * @return uint8 The decimals of the token.
      */
     function decimals() external returns (uint8);
 }

contracts/interfaces/IFlowLimit.sol

@@ -2,26 +2,30 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title FlowLimit Interface
+ * @notice Interface for flow limit logic for interchain token transfers.
+ */
 interface IFlowLimit {
     error FlowLimitExceeded(uint256 limit, uint256 flowAmount);
 
     event FlowLimitSet(bytes32 indexed tokenId, address operator, uint256 flowLimit);
 
     /**
-     * @notice Returns the current flow limit
-     * @return flowLimit The current flow limit value
+     * @notice Returns the current flow limit.
+     * @return flowLimit The current flow limit value.
      */
     function getFlowLimit() external view returns (uint256 flowLimit);
 
     /**
-     * @notice Returns the current flow out amount
-     * @return flowOutAmount The current flow out amount
+     * @notice Returns the current flow out amount.
+     * @return flowOutAmount The current flow out amount.
      */
     function getFlowOutAmount() external view returns (uint256 flowOutAmount);
 
     /**
-     * @notice Returns the current flow in amount
-     * @return flowInAmount The current flow in amount
+     * @notice Returns the current flow in amount.
+     * @return flowInAmount The current flow in amount.
      */
     function getFlowInAmount() external view returns (uint256 flowInAmount);
 }

contracts/interfaces/IImplementation.sol

@@ -2,6 +2,10 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IImplementation Interface
+ * @notice An interface for proxy contract implementations.
+ */
 interface IImplementation {
     error NotProxy();
 

contracts/interfaces/IInterchainToken.sol

@@ -11,14 +11,14 @@ interface IInterchainToken {
     /**
      * @notice Getter for the tokenManager used for this token.
      * @dev Needs to be overwitten.
-     * @return tokenManager_ the TokenManager called to facilitate cross chain transfers.
+     * @return tokenManager_ The TokenManager called to facilitate cross chain transfers.
      */
     function tokenManager() external view returns (ITokenManager tokenManager_);
 
     /**
      * @notice Implementation of the interchainTransfer method
-     * @dev We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer.
-     * A different implementation could have `metadata` that tells this function which function to use or that it is used for anything else as well.
+     * @dev We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer.
+     * A different implementation could use metadata to specify a function to invoke, or for other purposes as well.
      * @param destinationChain The destination chain identifier.
      * @param recipient The bytes representation of the address of the recipient.
      * @param amount The amount of token to be transferred.
@@ -34,12 +34,12 @@ interface IInterchainToken {
     /**
      * @notice Implementation of the interchainTransferFrom method
      * @dev We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer.
-     * A different implementation could have `metadata` that tells this function which function to use or that it is used for anything else as well.
-     * @param sender the sender of the tokens. They need to have approved `msg.sender` before this is called.
-     * @param destinationChain the string representation of the destination chain.
-     * @param recipient the bytes representation of the address of the recipient.
-     * @param amount the amount of token to be transferred.
-     * @param metadata either empty, to just facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
+     * A different implementation could use metadata to specify a function to invoke, or for other purposes as well.
+     * @param sender The sender of the tokens. They need to have approved `msg.sender` before this is called.
+     * @param destinationChain The string representation of the destination chain.
+     * @param recipient The bytes representation of the address of the recipient.
+     * @param amount The amount of token to be transferred.
+     * @param metadata Either empty, to just facilitate a cross-chain transfer, or the data to be passed to a cross-chain contract call and transfer.
      */
     function interchainTransferFrom(
         address sender,

contracts/interfaces/IInterchainTokenExecutable.sol

@@ -3,19 +3,19 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title IInterchainTokenExecutable
- * @notice Implement this to accept calls from the InterchainTokenService.
+ * @title IInterchainTokenExecutable Interface
+ * @notice This interface contains functions for accepting calls from the InterchainTokenService.
  */
 interface IInterchainTokenExecutable {
     /**
-     * @notice This will be called after the tokens arrive to this contract
-     * @dev Executable should revert unless the msg.sender is the InterchainTokenService
-     * @param sourceChain the name of the source chain
-     * @param sourceAddress the address that sent the contract call
-     * @param data the data to be processed
-     * @param tokenId the tokenId of the token manager managing the token.
-     * @param token the address of the token.
-     * @param amount the amount of token that was sent
+     * @notice This will be called after the tokens are sent to this contract.
+     * @dev Execution should revert unless the msg.sender is the InterchainTokenService
+     * @param sourceChain The name of the source chain.
+     * @param sourceAddress The address that sent the contract call.
+     * @param data The data to be processed.
+     * @param tokenId The tokenId of the token manager managing the token.
+     * @param token The address of the token.
+     * @param amount The amount of tokens that were sent.
      */
     function executeWithInterchainToken(
         string calldata sourceChain,

contracts/interfaces/IInterchainTokenExpressExecutable.sol

@@ -5,19 +5,19 @@ pragma solidity ^0.8.0;
 import { IInterchainTokenExecutable } from './IInterchainTokenExecutable.sol';
 
 /**
- * @title IInterchainTokenExpressExecutable
- * @notice Implement this to accept express calls from the InterchainTokenService.
+ * @title IInterchainTokenExpressExecutable Interface
+ * @notice This interface contains functions for accepting express calls from the InterchainTokenService.
  */
 interface IInterchainTokenExpressExecutable is IInterchainTokenExecutable {
     /**
-     * @notice This will be called after the tokens arrive to this contract
-     * @dev Executable should revert unless the msg.sender is the InterchainTokenService
-     * @param sourceChain the name of the source chain
-     * @param sourceAddress the address that sent the contract call
-     * @param data the data to be processed
-     * @param tokenId the token id of the token manager managing the token.
-     * @param token the address of the token.
-     * @param amount the amount of token that was sent
+     * @notice This will be called after the tokens are sent to this contract.
+     * @dev Execution should revert unless the msg.sender is the InterchainTokenService.
+     * @param sourceChain The name of the source chain.
+     * @param sourceAddress The address that sent the contract call.
+     * @param data The data to be processed.
+     * @param tokenId The token id of the token manager managing the token.
+     * @param token The address of the token.
+     * @param amount The amount of token that was sent.
      */
     function expressExecuteWithInterchainToken(
         string calldata sourceChain,

contracts/interfaces/IInterchainTokenService.sol

@@ -10,6 +10,10 @@ import { IPausable } from './IPausable.sol';
 import { IMulticall } from './IMulticall.sol';
 import { IRemoteAddressValidator } from './IRemoteAddressValidator.sol';
 
+/**
+ * @title IInterchainTokenService Interface
+ * @notice Interface for the Interchain Token Service
+ */
 interface IInterchainTokenService is ITokenManagerType, IAxelarValuedExpressExecutable, IPausable, IMulticall, IContractIdentifier {
     error ZeroAddress();
     error LengthMismatch();
@@ -189,7 +193,8 @@ interface IInterchainTokenService is ITokenManagerType, IAxelarValuedExpressExec
     ) external payable returns (bytes32 tokenId);
 
     /**
-     * @notice Deploys a standardized token and registers it. The token manager type will be lock/unlock unless the distributor matches its address, in which case it will be a mint/burn one.
+     * @notice Deploys a standardized token and registers it.
+     * @dev The token manager type will be lock/unlock unless the distributor matches its address, in which case it will be a mint/burn one.
      * @param salt The salt used for token deployment.
      * @param name The name of the standardized token.
      * @param symbol The symbol of the standardized token.
@@ -239,6 +244,14 @@ interface IInterchainTokenService is ITokenManagerType, IAxelarValuedExpressExec
      */
     function getImplementation(uint256 tokenManagerType) external view returns (address tokenManagerAddress);
 
+    /**
+     * @notice Initiates an interchain transfer of a specified token to a destination chain.
+     * @param tokenId The unique identifier of the token to be transferred.
+     * @param destinationChain The destination chain to send the tokens to.
+     * @param destinationAddress The address on the destination chain to send the tokens to.
+     * @param amount The amount of tokens to be transferred.
+     * @param metadata Additional data to be passed along with the transfer.
+     */
     function interchainTransfer(
         bytes32 tokenId,
         string calldata destinationChain,
@@ -247,6 +260,14 @@ interface IInterchainTokenService is ITokenManagerType, IAxelarValuedExpressExec
         bytes calldata metadata
     ) external payable;
 
+    /**
+     * @notice Sends tokens to a specified address on a destination chain along with additional data.
+     * @param tokenId The unique identifier of the token to be sent.
+     * @param destinationChain The destination chain where the tokens will be sent.
+     * @param destinationAddress The address on the destination chain where the tokens will be sent.
+     * @param amount The amount of tokens to be sent.
+     * @param data Additional data to be sent along with the tokens.
+     */
     function sendTokenWithData(
         bytes32 tokenId,
         string calldata destinationChain,
@@ -256,7 +277,8 @@ interface IInterchainTokenService is ITokenManagerType, IAxelarValuedExpressExec
     ) external payable;
 
     /**
-     * @notice Initiates an interchain token transfer. Only callable by TokenManagers
+     * @notice Initiates an interchain token transfer.
+     * @dev Only callable by TokenManagers.
      * @param tokenId The tokenId of the token to be transmitted.
      * @param sourceAddress The source address of the token.
      * @param destinationChain The name of the destination chain.

contracts/interfaces/IMockAxelarGateway.sol

@@ -3,6 +3,7 @@
 pragma solidity ^0.8.0;
 
 /**
+ * @title IMockAxelarGateway Interface
  * @notice This interface is used for testing with an AxelarGateway that will arbitrarily approve calls.
  */
 interface IMockAxelarGateway {