evm: More minor natspec improvements (#495)

Author: djb15

evm/src/interfaces/IManagerBase.sol

@@ -106,11 +106,11 @@ interface IManagerBase {
 
     /// @notice Error when the manager doesn't have a peer registered for the destination chain
     /// @dev Selector 0x3af256bc.
-    /// @param chainId The target chain id
+    /// @param chainId The target Wormhole chain id
     error PeerNotRegistered(uint16 chainId);
 
     /// @notice Fetch the delivery price for a given recipient chain transfer.
-    /// @param recipientChain The chain ID of the transfer destination.
+    /// @param recipientChain The Wormhole chain ID of the transfer destination.
     /// @param transceiverInstructions The transceiver specific instructions for quoting and sending
     /// @return - The delivery prices associated with each enabled endpoint and the total price.
     function quoteDeliveryPrice(
@@ -120,7 +120,7 @@ interface IManagerBase {
 
     /// @notice Sets the threshold for the number of attestations required for a message
     /// to be considered valid.
-    /// @param threshold The new threshold.
+    /// @param threshold The new threshold (number of attestations).
     /// @dev This method can only be executed by the `owner`.
     function setThreshold(uint8 threshold) external;
 
@@ -166,12 +166,17 @@ interface IManagerBase {
     function getThreshold() external view returns (uint8);
 
     /// @notice Returns a boolean indicating if the transceiver has attested to the message.
+    /// @param digest The digest of the message.
+    /// @param index The index of the transceiver
+    /// @return - Boolean indicating whether the transceiver at index `index` attested to a message digest
     function transceiverAttestedToMessage(
         bytes32 digest,
         uint8 index
     ) external view returns (bool);
 
     /// @notice Returns the number of attestations for a given message.
+    /// @param digest The digest of the message.
+    /// @return count The number of attestations received for the given message digest
     function messageAttestations(bytes32 digest) external view returns (uint8 count);
 
     /// @notice Returns of the address of the token managed by this contract.

evm/src/interfaces/INttManager.sol

@@ -140,8 +140,9 @@ interface INttManager is IManagerBase {
     ///         sender's tokens. Finally, this function will call into registered `Endpoint` contracts
     ///         to send a message with the incrementing sequence number and the token transfer payload.
     /// @param amount The amount to transfer.
-    /// @param recipientChain The chain ID for the destination.
+    /// @param recipientChain The Wormhole chain ID for the destination.
     /// @param recipient The recipient address.
+    /// @return msgId The resulting message ID of the transfer
     function transfer(
         uint256 amount,
         uint16 recipientChain,
@@ -154,11 +155,12 @@ interface INttManager is IManagerBase {
     ///         to send a message with the incrementing sequence number and the token transfer payload.
     /// @dev Transfers are queued if the outbound limit is hit and must be completed by the client.
     /// @param amount The amount to transfer.
-    /// @param recipientChain The chain ID for the destination.
+    /// @param recipientChain The Wormhole chain ID for the destination.
     /// @param recipient The recipient address.
     /// @param refundAddress The address to which a refund for unussed gas is issued on the recipient chain.
     /// @param shouldQueue Whether the transfer should be queued if the outbound limit is hit.
     /// @param encodedInstructions Additional instructions to be forwarded to the recipient chain.
+    /// @return msgId The resulting message ID of the transfer
     function transfer(
         uint256 amount,
         uint16 recipientChain,
@@ -189,8 +191,8 @@ interface INttManager is IManagerBase {
     /// @dev This function enforces attestation threshold and replay logic for messages. Once all
     ///      validations are complete, this function calls `executeMsg` to execute the command specified
     ///      by the message.
-    /// @param sourceChainId The chain id of the sender.
-    /// @param sourceNttManagerAddress The address of the sender's nttManager contract.
+    /// @param sourceChainId The Wormhole chain id of the sender.
+    /// @param sourceNttManagerAddress The address of the sender's NTT Manager contract.
     /// @param payload The VAA payload.
     function attestationReceived(
         uint16 sourceChainId,
@@ -203,7 +205,7 @@ interface INttManager is IManagerBase {
     ///         as an NttManagerMessage to extract the sequence, msgType, and other parameters.
     /// @dev This function is exposed as a fallback for when an `Transceiver` is deregistered
     ///      when a message is in flight.
-    /// @param sourceChainId The chain id of the sender.
+    /// @param sourceChainId The Wormhole chain id of the sender.
     /// @param sourceNttManagerAddress The address of the sender's nttManager contract.
     /// @param message The message to execute.
     function executeMsg(
@@ -217,15 +219,16 @@ interface INttManager is IManagerBase {
     function tokenDecimals() external view returns (uint8);
 
     /// @notice Returns registered peer contract for a given chain.
-    /// @param chainId_ chain ID.
+    /// @param chainId_ Wormhole chain ID.
     function getPeer(uint16 chainId_) external view returns (NttManagerPeer memory);
 
     /// @notice Sets the corresponding peer.
     /// @dev The nttManager that executes the message sets the source nttManager as the peer.
-    /// @param peerChainId The chain ID of the peer.
+    /// @param peerChainId The Wormhole chain ID of the peer.
     /// @param peerContract The address of the peer nttManager contract.
     /// @param decimals The number of decimals of the token on the peer chain.
-    /// @param inboundLimit The inbound rate limit for the peer chain id
+    /// @param inboundLimit The inbound rate limit for the peer chain id. This is formatted in the normal
+    ///                     token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000
     function setPeer(
         uint16 peerChainId,
         bytes32 peerContract,
@@ -235,12 +238,14 @@ interface INttManager is IManagerBase {
 
     /// @notice Sets the outbound transfer limit for a given chain.
     /// @dev This method can only be executed by the `owner`.
-    /// @param limit The new outbound limit.
+    /// @param limit The new outbound limit. This is formatted in the normal
+    ///              token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000
     function setOutboundLimit(uint256 limit) external;
 
     /// @notice Sets the inbound transfer limit for a given chain.
     /// @dev This method can only be executed by the `owner`.
-    /// @param limit The new limit.
-    /// @param chainId The chain to set the limit for.
+    /// @param limit The new limit. This is formatted in the normal
+    ///              token representation. e.g. a limit of 100 for a token with 6 decimals = 100_000_000
+    /// @param chainId The Wormhole chain ID to set the limit for.
     function setInboundLimit(uint256 limit, uint16 chainId) external;
 }

evm/src/interfaces/IRateLimiter.sol

@@ -84,14 +84,23 @@ interface IRateLimiter {
         address recipient;
     }
 
+    /// @notice Returns the currently remaining outbound capacity allowed
+    ///         before transfers are queued (if desired)
     function getCurrentOutboundCapacity() external view returns (uint256);
 
+    /// @notice Returns the queued transfer details for a given sequence in the outbound queue
+    /// @param queueSequence The position of the transfer in the outbound queue
     function getOutboundQueuedTransfer(
         uint64 queueSequence
     ) external view returns (OutboundQueuedTransfer memory);
 
+    /// @notice Returns the currently remaining inbound capacity allowed from a given chain
+    ///         before transfers are queued auutomatically
+    /// @param chainId The Wormhole chain ID of the peer
     function getCurrentInboundCapacity(uint16 chainId) external view returns (uint256);
 
+    /// @notice Returns the queued transfer details for a given message digest in the inbound queue
+    /// @param digest The digest of the transfer in the inbound queue
     function getInboundQueuedTransfer(
         bytes32 digest
     ) external view returns (InboundQueuedTransfer memory);

evm/src/interfaces/ITransceiver.sol

@@ -62,6 +62,8 @@ interface ITransceiver {
     /// @param instruction An additional Instruction provided by the Transceiver to be
     /// executed on the recipient chain.
     /// @param nttManagerMessage A message to be sent to the nttManager on the recipient chain.
+    /// @param recipientNttManagerAddress The Wormhole formatted address of the peer NTT Manager on the recipient chain.
+    /// @param refundAddress The Wormhole formatted address of the refund recipient
     function sendMessage(
         uint16 recipientChain,
         TransceiverStructs.TransceiverInstruction memory instruction,
@@ -71,8 +73,10 @@ interface ITransceiver {
     ) external payable;
 
     /// @notice Upgrades the transceiver to a new implementation.
+    /// @param newImplementation The address of the new implementation contract
     function upgrade(address newImplementation) external;
 
     /// @notice Transfers the ownership of the transceiver to a new address.
+    /// @param newOwner The address of the new owner
     function transferTransceiverOwnership(address newOwner) external;
 }