From 4dbc0b3f1035f5748b7fd280b75b564857d7dbd8 Mon Sep 17 00:00:00 2001 From: pahor167 <47992132+pahor167@users.noreply.github.com> Date: Mon, 8 Aug 2022 16:38:53 +0200 Subject: [PATCH] Format @return NatSpecs correctly (#9733) * Format @return NatSpecs correctly * lint fix * PR comment * Update packages/protocol/contracts/common/Accounts.sol Co-authored-by: Martin * Update packages/protocol/contracts/common/linkedlists/AddressSortedLinkedList.sol Co-authored-by: Martin * PR comments 2 * typo fix * Update packages/protocol/contracts/governance/BlockchainParameters.sol Co-authored-by: Martin Co-authored-by: pahor167 Co-authored-by: Martin --- .../protocol/contracts/common/Accounts.sol | 16 +++++--- .../contracts/common/GasPriceMinimum.sol | 5 ++- .../protocol/contracts/common/GoldToken.sol | 5 ++- .../common/MetaTransactionWallet.sol | 8 +++- .../common/MetaTransactionWalletDeployer.sol | 7 +++- .../contracts/common/UsingPrecompiles.sol | 3 +- .../interfaces/ICeloVersionedContract.sol | 5 ++- .../linkedlists/AddressSortedLinkedList.sol | 3 +- .../AddressSortedLinkedListWithMedian.sol | 4 +- .../linkedlists/IntegerSortedLinkedList.sol | 3 +- .../common/linkedlists/SortedLinkedList.sol | 6 ++- .../SortedLinkedListWithMedian.sol | 4 +- .../governance/BlockchainParameters.sol | 11 ++++-- .../governance/DoubleSigningSlasher.sol | 5 ++- .../contracts/governance/DowntimeSlasher.sol | 5 ++- .../contracts/governance/Election.sol | 13 +++++-- .../contracts/governance/EpochRewards.sol | 19 ++++++--- .../contracts/governance/Governance.sol | 39 ++++++++++++++----- .../contracts/governance/LockedGold.sol | 8 +++- .../contracts/governance/Proposals.sol | 14 +++++-- .../contracts/governance/Validators.sol | 27 ++++++++++--- .../contracts/identity/Attestations.sol | 37 +++++++++--------- .../protocol/contracts/identity/Escrow.sol | 5 ++- .../protocol/contracts/identity/Random.sol | 5 ++- .../protocol/contracts/stability/Exchange.sol | 20 +++++++--- .../contracts/stability/ExchangeBRL.sol | 5 ++- .../contracts/stability/ExchangeEUR.sol | 5 ++- .../contracts/stability/GrandaMento.sol | 11 ++++-- .../protocol/contracts/stability/Reserve.sol | 8 +++- .../contracts/stability/SortedOracles.sol | 17 ++++++-- .../contracts/stability/StableToken.sol | 5 ++- .../contracts/stability/StableTokenBRL.sol | 5 ++- .../contracts/stability/StableTokenEUR.sol | 5 ++- .../stability/StableTokenRegistry.sol | 8 +++- .../scripts/generate-stabletoken-files.ts | 10 ++++- 35 files changed, 258 insertions(+), 98 deletions(-) diff --git a/packages/protocol/contracts/common/Accounts.sol b/packages/protocol/contracts/common/Accounts.sol index b24cc6c8b2a..92713092724 100644 --- a/packages/protocol/contracts/common/Accounts.sol +++ b/packages/protocol/contracts/common/Accounts.sol @@ -123,7 +123,10 @@ contract Accounts is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 4, 0); @@ -287,7 +290,8 @@ contract Accounts is /** * @notice Returns the full list of offchain storage roots for an account. * @param account The account whose storage roots to return. - * @return List of storage root URLs. + * @return Concatenated storage root URLs. + * @return Lengths of storage root URLs. */ function getOffchainStorageRoots(address account) external @@ -347,7 +351,8 @@ contract Accounts is /** * @notice Gets validator payment delegation settings. * @param account Account of the validator. - * @return Beneficiary address and fraction of payment delegated. + * @return Beneficiary address of payment delegated. + * @return Fraction of payment delegated. */ function getPaymentDelegation(address account) external view returns (address, uint256) { PaymentDelegation storage delegation = paymentDelegations[account]; @@ -946,9 +951,8 @@ contract Accounts is /** * @notice Getter for the metadata of multiple accounts. * @param accountsToQuery The addresses of the accounts to get the metadata for. - * @return (stringLengths[] - the length of each string in bytes - * data - all strings concatenated - * ) + * @return The length of each string in bytes. + * @return All strings concatenated. */ function batchGetMetadataURL(address[] calldata accountsToQuery) external diff --git a/packages/protocol/contracts/common/GasPriceMinimum.sol b/packages/protocol/contracts/common/GasPriceMinimum.sol index 068ab77a87b..de8a7ced97f 100644 --- a/packages/protocol/contracts/common/GasPriceMinimum.sol +++ b/packages/protocol/contracts/common/GasPriceMinimum.sol @@ -45,7 +45,10 @@ contract GasPriceMinimum is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 0); diff --git a/packages/protocol/contracts/common/GoldToken.sol b/packages/protocol/contracts/common/GoldToken.sol index 3986376b5a8..2226c092c52 100644 --- a/packages/protocol/contracts/common/GoldToken.sol +++ b/packages/protocol/contracts/common/GoldToken.sol @@ -45,7 +45,10 @@ contract GoldToken is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 1); diff --git a/packages/protocol/contracts/common/MetaTransactionWallet.sol b/packages/protocol/contracts/common/MetaTransactionWallet.sol index 9eb7ed16562..bb092447567 100644 --- a/packages/protocol/contracts/common/MetaTransactionWallet.sol +++ b/packages/protocol/contracts/common/MetaTransactionWallet.sol @@ -70,7 +70,10 @@ contract MetaTransactionWallet is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 1); @@ -260,7 +263,8 @@ contract MetaTransactionWallet is * @param values The CELO value to be sent with each transaction. * @param data The concatenated data to be sent in each transaction. * @param dataLengths The length of each transaction's data. - * @return The return values of all transactions appended as bytes and an array of the length + * @return All transactions appended as bytes + * @return An array of the length * of each transaction output which will be 0 if a transaction had no output */ function executeTransactions( diff --git a/packages/protocol/contracts/common/MetaTransactionWalletDeployer.sol b/packages/protocol/contracts/common/MetaTransactionWalletDeployer.sol index b343a64cd67..7ea3d05233a 100644 --- a/packages/protocol/contracts/common/MetaTransactionWalletDeployer.sol +++ b/packages/protocol/contracts/common/MetaTransactionWalletDeployer.sol @@ -8,8 +8,11 @@ contract MetaTransactionWalletDeployer is IMetaTransactionWalletDeployer, ICeloV event WalletDeployed(address indexed owner, address indexed wallet, address implementation); /** - * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @notice Returns the storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 1); diff --git a/packages/protocol/contracts/common/UsingPrecompiles.sol b/packages/protocol/contracts/common/UsingPrecompiles.sol index c0a6e92ef42..144955921d9 100644 --- a/packages/protocol/contracts/common/UsingPrecompiles.sol +++ b/packages/protocol/contracts/common/UsingPrecompiles.sol @@ -25,7 +25,8 @@ contract UsingPrecompiles { * @param bDenominator Denominator of exponentiated fraction * @param exponent exponent to raise b to * @param _decimals precision - * @return numerator/denominator of the computed quantity (not reduced). + * @return Numerator of the computed quantity (not reduced). + * @return Denominator of the computed quantity (not reduced). */ function fractionMulExp( uint256 aNumerator, diff --git a/packages/protocol/contracts/common/interfaces/ICeloVersionedContract.sol b/packages/protocol/contracts/common/interfaces/ICeloVersionedContract.sol index 7b13155a481..49d30da5aa0 100644 --- a/packages/protocol/contracts/common/interfaces/ICeloVersionedContract.sol +++ b/packages/protocol/contracts/common/interfaces/ICeloVersionedContract.sol @@ -3,7 +3,10 @@ pragma solidity ^0.5.13; interface ICeloVersionedContract { /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256); } diff --git a/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedList.sol b/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedList.sol index 5a74ecdcb48..9f90b8764e6 100644 --- a/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedList.sol +++ b/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedList.sol @@ -88,7 +88,8 @@ library AddressSortedLinkedList { /** * @notice Gets all elements from the doubly linked list. - * @return An unpacked list of elements from largest to smallest. + * @return Array of all keys in the list. + * @return Values corresponding to keys, which will be ordered largest to smallest. */ function getElements(SortedLinkedList.List storage list) public diff --git a/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedListWithMedian.sol b/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedListWithMedian.sol index 2cf62ee1d10..2a1f539078b 100644 --- a/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedListWithMedian.sol +++ b/packages/protocol/contracts/common/linkedlists/AddressSortedLinkedListWithMedian.sol @@ -149,7 +149,9 @@ library AddressSortedLinkedListWithMedian { /** * @notice Gets all elements from the doubly linked list. * @param list A storage pointer to the underlying list. - * @return An unpacked list of elements from largest to smallest. + * @return Array of all keys in the list. + * @return Values corresponding to keys, which will be ordered largest to smallest. + * @return Array of relations to median of corresponding list elements. */ function getElements(SortedLinkedListWithMedian.List storage list) public diff --git a/packages/protocol/contracts/common/linkedlists/IntegerSortedLinkedList.sol b/packages/protocol/contracts/common/linkedlists/IntegerSortedLinkedList.sol index 70fd1acec6d..a5123ac51d1 100644 --- a/packages/protocol/contracts/common/linkedlists/IntegerSortedLinkedList.sol +++ b/packages/protocol/contracts/common/linkedlists/IntegerSortedLinkedList.sol @@ -104,7 +104,8 @@ library IntegerSortedLinkedList { /** * @notice Gets all elements from the doubly linked list. * @param list A storage pointer to the underlying list. - * @return An unpacked list of elements from largest to smallest. + * @return Array of all keys in the list. + * @return Values corresponding to keys, which will be ordered largest to smallest. */ function getElements(SortedLinkedList.List storage list) public diff --git a/packages/protocol/contracts/common/linkedlists/SortedLinkedList.sol b/packages/protocol/contracts/common/linkedlists/SortedLinkedList.sol index 2ae68b24a48..25f92fcb20b 100644 --- a/packages/protocol/contracts/common/linkedlists/SortedLinkedList.sol +++ b/packages/protocol/contracts/common/linkedlists/SortedLinkedList.sol @@ -124,7 +124,8 @@ library SortedLinkedList { /** * @notice Gets all elements from the doubly linked list. * @param list A storage pointer to the underlying list. - * @return An unpacked list of elements from largest to smallest. + * @return Array of all keys in the list. + * @return Values corresponding to keys, which will be ordered largest to smallest. */ function getElements(List storage list) internal @@ -165,7 +166,8 @@ library SortedLinkedList { * @param value The element value. * @param lesserKey The key of the element which could be just left of the new value. * @param greaterKey The key of the element which could be just right of the new value. - * @return The correct lesserKey/greaterKey keys. + * @return The correct lesserKey keys. + * @return The correct greaterKey keys. */ function getLesserAndGreater( List storage list, diff --git a/packages/protocol/contracts/common/linkedlists/SortedLinkedListWithMedian.sol b/packages/protocol/contracts/common/linkedlists/SortedLinkedListWithMedian.sol index 57a2fc8f4c8..f7bf9414cf7 100644 --- a/packages/protocol/contracts/common/linkedlists/SortedLinkedListWithMedian.sol +++ b/packages/protocol/contracts/common/linkedlists/SortedLinkedListWithMedian.sol @@ -219,7 +219,9 @@ library SortedLinkedListWithMedian { /** * @notice Gets all elements from the doubly linked list. * @param list A storage pointer to the underlying list. - * @return An unpacked list of elements from largest to smallest. + * @return Array of all keys in the list. + * @return Values corresponding to keys, which will be ordered largest to smallest. + * @return Array of relations to median of corresponding list elements. */ function getElements(List storage list) internal diff --git a/packages/protocol/contracts/governance/BlockchainParameters.sol b/packages/protocol/contracts/governance/BlockchainParameters.sol index 80e5d275d27..1e9ccc4dc4d 100644 --- a/packages/protocol/contracts/governance/BlockchainParameters.sol +++ b/packages/protocol/contracts/governance/BlockchainParameters.sol @@ -68,7 +68,10 @@ contract BlockchainParameters is Ownable, Initializable, UsingPrecompiles { /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 2, 0, 0); @@ -147,8 +150,10 @@ contract BlockchainParameters is Ownable, Initializable, UsingPrecompiles { } /** - * @notice Query minimum client version. - * @return Returns major, minor, and patch version numbers. + * @notice Query minimum client version. + * @return Major version number. + * @return Minor version number. + * @return Patch version number. */ function getMinimumClientVersion() external diff --git a/packages/protocol/contracts/governance/DoubleSigningSlasher.sol b/packages/protocol/contracts/governance/DoubleSigningSlasher.sol index 853fc8347f1..cf2cd93b6d7 100644 --- a/packages/protocol/contracts/governance/DoubleSigningSlasher.sol +++ b/packages/protocol/contracts/governance/DoubleSigningSlasher.sol @@ -16,7 +16,10 @@ contract DoubleSigningSlasher is ICeloVersionedContract, SlasherUtil { /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 0); diff --git a/packages/protocol/contracts/governance/DowntimeSlasher.sol b/packages/protocol/contracts/governance/DowntimeSlasher.sol index 774abf75942..6e5480d8fde 100644 --- a/packages/protocol/contracts/governance/DowntimeSlasher.sol +++ b/packages/protocol/contracts/governance/DowntimeSlasher.sol @@ -33,7 +33,10 @@ contract DowntimeSlasher is ICeloVersionedContract, SlasherUtil { /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (2, 0, 0, 0); diff --git a/packages/protocol/contracts/governance/Election.sol b/packages/protocol/contracts/governance/Election.sol index 218de3b7e69..0785899fc8d 100644 --- a/packages/protocol/contracts/governance/Election.sol +++ b/packages/protocol/contracts/governance/Election.sol @@ -133,7 +133,10 @@ contract Election is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 2, 1); @@ -188,7 +191,8 @@ contract Election is /** * @notice Returns the minimum and maximum number of validators that can be elected. - * @return The minimum and maximum number of validators that can be elected. + * @return The minimum number of validators that can be elected. + * @return The maximum number of validators that can be elected. */ function getElectableValidators() external view returns (uint256, uint256) { return (electableValidators.min, electableValidators.max); @@ -928,8 +932,9 @@ contract Election is } /** - * @notice Returns lists of all validator groups and the number of votes they've received. - * @return Lists of all validator groups and the number of votes they've received. + * @notice Returns list of all validator groups and the number of votes they've received. + * @return List of all validator groups + * @return Number of votes each validator group received. */ function getTotalVotesForEligibleValidatorGroups() external diff --git a/packages/protocol/contracts/governance/EpochRewards.sol b/packages/protocol/contracts/governance/EpochRewards.sol index 5eab1eb1dd0..0c329e3e684 100644 --- a/packages/protocol/contracts/governance/EpochRewards.sol +++ b/packages/protocol/contracts/governance/EpochRewards.sol @@ -86,7 +86,10 @@ contract EpochRewards is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 0); @@ -148,7 +151,9 @@ contract EpochRewards is /** * @notice Returns the target voting yield parameters. - * @return The target, max, and adjustment factor for target voting yield. + * @return The target factor for target voting yield. + * @return The max factor for target voting yield. + * @return The adjustment factor for target voting yield. */ function getTargetVotingYieldParameters() external view returns (uint256, uint256, uint256) { TargetVotingYieldParameters storage params = targetVotingYieldParams; @@ -157,7 +162,9 @@ contract EpochRewards is /** * @notice Returns the rewards multiplier parameters. - * @return The max multiplier and under/over spend adjustment factors. + * @return The max multiplier. + * @return The underspend adjustment factors. + * @return The overspend adjustment factors. */ function getRewardsMultiplierParameters() external view returns (uint256, uint256, uint256) { RewardsMultiplierParameters storage params = rewardsMultiplierParams; @@ -514,8 +521,10 @@ contract EpochRewards is /** * @notice Calculates the per validator epoch payment and the total rewards to voters. - * @return The per validator epoch reward, the total rewards to voters, the total community - * reward, and the total carbon offsetting partner reward. + * @return The per validator epoch reward. + * @return The total rewards to voters. + * @return The total community reward. + * @return The total carbon offsetting partner reward. */ function calculateTargetEpochRewards() external diff --git a/packages/protocol/contracts/governance/Governance.sol b/packages/protocol/contracts/governance/Governance.sol index 7f62473ec9a..23e9a73dd05 100644 --- a/packages/protocol/contracts/governance/Governance.sol +++ b/packages/protocol/contracts/governance/Governance.sol @@ -197,7 +197,10 @@ contract Governance is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 2, 1, 1); @@ -491,7 +494,8 @@ contract Governance is /** * @notice Requires a proposal is dequeued and removes it if expired. * @param proposalId The ID of the proposal. - * @return The proposal storage struct and stage corresponding to `proposalId`. + * @return The proposal storage struct corresponding to `proposalId`. + * @return The proposal stage corresponding to `proposalId`. */ function requireDequeuedAndDeleteExpired(uint256 proposalId, uint256 index) private @@ -861,7 +865,10 @@ contract Governance is /** * @notice Returns the participation parameters. - * @return The participation parameters. + * @return baseline The participation baseline parameter. + * @return baselineFloor The participation baseline floor parameter. + * @return baselineUpdateFactor The participation baseline update factor parameter. + * @return baselineQuorumFactor The participation baseline quorum factor parameter. */ function getParticipationParameters() external view returns (uint256, uint256, uint256, uint256) { return ( @@ -884,7 +891,11 @@ contract Governance is /** * @notice Returns an unpacked proposal struct with its transaction count. * @param proposalId The ID of the proposal to unpack. - * @return The unpacked proposal with its transaction count. + * @return proposer + * @return deposit + * @return timestamp + * @return transaction Transaction count. + * @return description Description url. */ function getProposal(uint256 proposalId) external @@ -898,7 +909,9 @@ contract Governance is * @notice Returns a specified transaction in a proposal. * @param proposalId The ID of the proposal to query. * @param index The index of the specified transaction in the proposal's transaction list. - * @return The specified transaction. + * @return value Transaction value. + * @return destination Transaction destination. + * @return data Transaction data. */ function getProposalTransaction(uint256 proposalId, uint256 index) external @@ -920,7 +933,9 @@ contract Governance is /** * @notice Returns the referendum vote totals for a proposal. * @param proposalId The ID of the proposal. - * @return The yes, no, and abstain vote totals. + * @return yes The yes vote totals. + * @return no The no vote totals. + * @return abstain The abstain vote totals. */ function getVoteTotals(uint256 proposalId) external view returns (uint256, uint256, uint256) { return proposals[proposalId].getVoteTotals(); @@ -931,6 +946,8 @@ contract Governance is * @param account The address of the account to get the record for. * @param index The index in `dequeued`. * @return The corresponding proposal ID, vote value, and weight. + * @return The corresponding vote value. + * @return The corresponding weight. */ function getVoteRecord(address account, uint256 index) external @@ -961,7 +978,8 @@ contract Governance is /** * @notice Returns the proposal ID and upvote total for all queued proposals. - * @return The proposal ID and upvote total for all queued proposals. + * @return proposalID The proposal ID for all queued proposals. + * @return total The upvote total for all queued proposals. * @dev Note that this includes expired proposals that have yet to be removed from the queue. */ function getQueue() external view returns (uint256[] memory, uint256[] memory) { @@ -980,7 +998,8 @@ contract Governance is /** * @notice Returns the ID of the proposal upvoted by `account` and the weight of that upvote. * @param account The address of the account. - * @return The ID of the proposal upvoted by `account` and the weight of that upvote. + * @return The ID of the proposal upvoted by `account`. + * @return The weight of that upvote. */ function getUpvoteRecord(address account) external view returns (uint256, uint256) { UpvoteRecord memory upvoteRecord = voters[account].upvote; @@ -1030,7 +1049,9 @@ contract Governance is /** * @notice Gets information about a hotfix. * @param hash The abi encoded keccak256 hash of the hotfix transaction. - * @return Hotfix tuple of (approved, executed, preparedEpoch) + * @return Hotfix approved. + * @return Hotfix executed. + * @return Hotfix preparedEpoch. */ function getHotfixRecord(bytes32 hash) public view returns (bool, bool, uint256) { return (hotfixes[hash].approved, hotfixes[hash].executed, hotfixes[hash].preparedEpoch); diff --git a/packages/protocol/contracts/governance/LockedGold.sol b/packages/protocol/contracts/governance/LockedGold.sol index 3a798d8b9c1..4f25880eb81 100644 --- a/packages/protocol/contracts/governance/LockedGold.sol +++ b/packages/protocol/contracts/governance/LockedGold.sol @@ -78,7 +78,10 @@ contract LockedGold is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 2, 0); @@ -265,7 +268,8 @@ contract LockedGold is /** * @notice Returns the pending withdrawals from unlocked gold for an account. * @param account The address of the account. - * @return The value and timestamp for each pending withdrawal. + * @return The value for each pending withdrawal. + * @return The timestamp for each pending withdrawal. */ function getPendingWithdrawals(address account) external diff --git a/packages/protocol/contracts/governance/Proposals.sol b/packages/protocol/contracts/governance/Proposals.sol index 8e1b84a22a0..c0bc692986e 100644 --- a/packages/protocol/contracts/governance/Proposals.sol +++ b/packages/protocol/contracts/governance/Proposals.sol @@ -281,7 +281,9 @@ library Proposals { * @notice Returns a specified transaction in a proposal. * @param proposal The proposal struct. * @param index The index of the specified transaction in the proposal's transaction list. - * @return The specified transaction. + * @return Transaction value. + * @return Transaction destination. + * @return Transaction data. */ function getTransaction(Proposal storage proposal, uint256 index) public @@ -296,7 +298,11 @@ library Proposals { /** * @notice Returns an unpacked proposal struct with its transaction count. * @param proposal The proposal struct. - * @return The unpacked proposal with its transaction count. + * @return proposer + * @return deposit + * @return timestamp + * @return transaction Transaction count. + * @return description Description url. */ function unpack(Proposal storage proposal) internal @@ -315,7 +321,9 @@ library Proposals { /** * @notice Returns the referendum vote totals for a proposal. * @param proposal The proposal struct. - * @return The yes, no, and abstain vote totals. + * @return The yes vote totals. + * @return The no vote totals. + * @return The abstain vote totals. */ function getVoteTotals(Proposal storage proposal) internal diff --git a/packages/protocol/contracts/governance/Validators.sol b/packages/protocol/contracts/governance/Validators.sol index 60b9995e4c8..70ea6dde5e7 100644 --- a/packages/protocol/contracts/governance/Validators.sol +++ b/packages/protocol/contracts/governance/Validators.sol @@ -160,7 +160,10 @@ contract Validators is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 2, 0, 3); @@ -374,7 +377,8 @@ contract Validators is /** * @notice Returns the parameters that govern how a validator's score is calculated. - * @return The parameters that goven how a validator's score is calculated. + * @return The exponent that governs how a validator's score is calculated. + * @return The adjustment speed that governs how a validator's score is calculated. */ function getValidatorScoreParameters() external view returns (uint256, uint256) { return (validatorScoreParameters.exponent, validatorScoreParameters.adjustmentSpeed.unwrap()); @@ -383,7 +387,10 @@ contract Validators is /** * @notice Returns the group membership history of a validator. * @param account The validator whose membership history to return. - * @return The group membership history of a validator. + * @return epochs The epochs of a validator. + * @return The membership groups of a validator. + * @return The last removed from group timestamp of a validator. + * @return The tail of a validator. */ function getMembershipHistory(address account) external @@ -989,7 +996,13 @@ contract Validators is /** * @notice Returns validator group information. * @param account The account that registered the validator group. - * @return The unpacked validator group struct. + * @return keys The Keys. + * @return commision The commision. + * @return nextCommision The next commision. + * @return nextCommisionBlock The next commision block. + * @return size The Size history. + * @return multiplier The multiplier. + * @return lastSlashed The last slashed. */ function getValidatorGroup(address account) external @@ -1065,7 +1078,8 @@ contract Validators is /** * @notice Returns the Locked Gold requirements for validators. - * @return The Locked Gold requirements for validators. + * @return The Locked Gold value. + * @return The Locked Gold duration. */ function getValidatorLockedGoldRequirements() external view returns (uint256, uint256) { return (validatorLockedGoldRequirements.value, validatorLockedGoldRequirements.duration); @@ -1073,7 +1087,8 @@ contract Validators is /** * @notice Returns the Locked Gold requirements for validator groups. - * @return The Locked Gold requirements for validator groups. + * @return The Locked Gold value. + * @return The Locked Gold duration. */ function getGroupLockedGoldRequirements() external view returns (uint256, uint256) { return (groupLockedGoldRequirements.value, groupLockedGoldRequirements.duration); diff --git a/packages/protocol/contracts/identity/Attestations.sol b/packages/protocol/contracts/identity/Attestations.sol index 147b03613c8..d5aa43794fe 100644 --- a/packages/protocol/contracts/identity/Attestations.sol +++ b/packages/protocol/contracts/identity/Attestations.sol @@ -174,7 +174,10 @@ contract Attestations is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 2); @@ -337,11 +340,9 @@ contract Attestations is * @notice Returns the unselected attestation request for an identifier/account pair, if any. * @param identifier Hash of the identifier. * @param account Address of the account. - * @return [ - * Block number at which was requested, - * Number of unselected requests, - * Address of the token with which this attestation request was paid for - * ] + * @return block Block number at which was requested. + * @return number Number of unselected requests. + * @return address Address of the token with which this attestation request was paid for. */ function getUnselectedRequest(bytes32 identifier, address account) external @@ -373,7 +374,8 @@ contract Attestations is * @notice Returns attestation stats for a identifier/account pair. * @param identifier Hash of the identifier. * @param account Address of the account. - * @return [Number of completed attestations, Number of total requested attestations] + * @return completed Number of completed attestations. + * @return requested Number of total requested attestations. */ function getAttestationStats(bytes32 identifier, address account) external @@ -432,11 +434,9 @@ contract Attestations is * @param identifier Hash of the identifier. * @param account Address of the account. * @param issuer Address of the issuer. - * @return [ - * Status of the attestation, - * Block number of request/completion the attestation, - * Address of the token with which this attestation request was paid for - * ] + * @return status Status of the attestation. + * @return block Block number of request/completion the attestation. + * @return address Address of the token with which this attestation request was paid for. */ function getAttestationState(bytes32 identifier, address account, address issuer) external @@ -457,11 +457,10 @@ contract Attestations is * @notice Returns the state of all attestations that are completable * @param identifier Hash of the identifier. * @param account Address of the account. - * @return ( blockNumbers[] - Block number of request/completion the attestation, - * issuers[] - Address of the issuer, - * stringLengths[] - The length of each metadataURL string for each issuer, - * stringData - All strings concatenated - * ) + * @return Block number of request/completion the attestation. + * @return Address of the issuer. + * @return The length of each metadataURL string for each issuer. + * @return All strings concatenated. */ function getCompletableAttestations(bytes32 identifier, address account) external @@ -619,8 +618,8 @@ contract Attestations is * @notice Helper function for batchGetAttestationStats to calculate the total number of addresses that have >0 complete attestations for the identifiers. * @param identifiersToLookup Array of n identifiers. - * @return Array of n numbers that indicate the number of matching addresses per identifier - * and array of addresses preallocated for total number of matches. + * @return Array of numbers that indicate the number of matching addresses per identifier. + * @return Array of addresses preallocated for total number of matches. */ function batchlookupAccountsForIdentifier(bytes32[] memory identifiersToLookup) internal diff --git a/packages/protocol/contracts/identity/Escrow.sol b/packages/protocol/contracts/identity/Escrow.sol index 285dd5ce55a..d912a69c9f6 100644 --- a/packages/protocol/contracts/identity/Escrow.sol +++ b/packages/protocol/contracts/identity/Escrow.sol @@ -71,7 +71,10 @@ contract Escrow is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 2); diff --git a/packages/protocol/contracts/identity/Random.sol b/packages/protocol/contracts/identity/Random.sol index 93f28253467..87cf5c3d9f0 100644 --- a/packages/protocol/contracts/identity/Random.sol +++ b/packages/protocol/contracts/identity/Random.sol @@ -36,7 +36,10 @@ contract Random is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 1, 0); diff --git a/packages/protocol/contracts/stability/Exchange.sol b/packages/protocol/contracts/stability/Exchange.sol index 3886b9d4a3f..96839f21ba0 100644 --- a/packages/protocol/contracts/stability/Exchange.sol +++ b/packages/protocol/contracts/stability/Exchange.sol @@ -69,7 +69,10 @@ contract Exchange is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 3, 0, 0); @@ -260,7 +263,8 @@ contract Exchange is * @notice Returns the buy token and sell token bucket sizes, in order. The ratio of * the two also represents the exchange rate between the two. * @param sellGold `true` if gold is the sell token. - * @return (buyTokenBucket, sellTokenBucket) + * @return buyTokenBucket + * @return sellTokenBucket */ function getBuyAndSellBuckets(bool sellGold) public view returns (uint256, uint256) { uint256 currentGoldBucket = goldBucket; @@ -363,7 +367,8 @@ contract Exchange is * @notice Returns the buy token and sell token bucket sizes, in order. The ratio of * the two also represents the exchange rate between the two. * @param sellGold `true` if gold is the sell token. - * @return (buyTokenBucket, sellTokenBucket) + * @return buyTokenBucket + * @return sellTokenBucket */ function _getBuyAndSellBuckets(bool sellGold) private view returns (uint256, uint256) { if (sellGold) { @@ -426,6 +431,10 @@ contract Exchange is return numerator.unwrap().div(denominator.unwrap()); } + /** + * @return buyTokenBucket + * @return sellTokenBucket + */ function getUpdatedBuckets() private view returns (uint256, uint256) { uint256 updatedGoldBucket = getUpdatedGoldBucket(); uint256 exchangeRateNumerator; @@ -488,9 +497,10 @@ contract Exchange is return FixidityLib.fixed1().subtract(spread).multiply(FixidityLib.newFixed(sellAmount)); } - /* + /** * @notice Checks conditions required for bucket updates. - * @return Whether or not buckets should be updated. + * @return The Rate numerator - whether or not buckets should be updated. + * @return The rate denominator - whether or not buckets should be updated. */ function shouldUpdateBuckets() private view returns (bool) { ISortedOracles sortedOracles = ISortedOracles( diff --git a/packages/protocol/contracts/stability/ExchangeBRL.sol b/packages/protocol/contracts/stability/ExchangeBRL.sol index 23884b5c40f..dec530f292e 100644 --- a/packages/protocol/contracts/stability/ExchangeBRL.sol +++ b/packages/protocol/contracts/stability/ExchangeBRL.sol @@ -12,7 +12,10 @@ contract ExchangeBRL is Exchange { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from Exchange.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 3, 0, 0); diff --git a/packages/protocol/contracts/stability/ExchangeEUR.sol b/packages/protocol/contracts/stability/ExchangeEUR.sol index af05cebbf2d..0b6523fece3 100644 --- a/packages/protocol/contracts/stability/ExchangeEUR.sol +++ b/packages/protocol/contracts/stability/ExchangeEUR.sol @@ -12,7 +12,10 @@ contract ExchangeEUR is Exchange { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from Exchange.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 3, 0, 0); diff --git a/packages/protocol/contracts/stability/GrandaMento.sol b/packages/protocol/contracts/stability/GrandaMento.sol index 6c29c529773..740befd26e1 100644 --- a/packages/protocol/contracts/stability/GrandaMento.sol +++ b/packages/protocol/contracts/stability/GrandaMento.sol @@ -164,7 +164,10 @@ contract GrandaMento is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 1); @@ -394,7 +397,8 @@ contract GrandaMento is * @dev For stable token sell amounts that are stored as units, the value * is returned. Ensures sell amount is not greater than this contract's balance. * @param proposal The proposal to get the sell token and sell amount for. - * @return (the IERC20 sell token, the value sell amount). + * @return The IERC20 sell token. + * @return The value sell amount. */ function getSellTokenAndSellAmount(ExchangeProposal memory proposal) private @@ -533,7 +537,8 @@ contract GrandaMento is * involved in a single exchange. * @dev Reverts if there is no explicit exchange limit for the stable token. * @param stableTokenRegistryId The string registry ID for the stable token. - * @return (minimum exchange amount, maximum exchange amount). + * @return Minimum exchange amount. + * @return Maximum exchange amount. */ function getStableTokenExchangeLimits(string memory stableTokenRegistryId) public diff --git a/packages/protocol/contracts/stability/Reserve.sol b/packages/protocol/contracts/stability/Reserve.sol index 61e378555af..72eb3c062d3 100644 --- a/packages/protocol/contracts/stability/Reserve.sol +++ b/packages/protocol/contracts/stability/Reserve.sol @@ -86,7 +86,10 @@ contract Reserve is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 2, 2); @@ -424,7 +427,8 @@ contract Reserve is /** * @notice Returns the tobin tax, recomputing it if it's stale. - * @return The tobin tax amount as a fraction. + * @return The numerator - tobin tax amount as a fraction. + * @return The denominator - tobin tax amount as a fraction. */ function getOrComputeTobinTax() external nonReentrant returns (uint256, uint256) { // solhint-disable-next-line not-rely-on-time diff --git a/packages/protocol/contracts/stability/SortedOracles.sol b/packages/protocol/contracts/stability/SortedOracles.sol index 137a7851247..4c35ce5404d 100644 --- a/packages/protocol/contracts/stability/SortedOracles.sol +++ b/packages/protocol/contracts/stability/SortedOracles.sol @@ -56,7 +56,10 @@ contract SortedOracles is ISortedOracles, ICeloVersionedContract, Ownable, Initi /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 2, 1); @@ -164,7 +167,8 @@ contract SortedOracles is ISortedOracles, ICeloVersionedContract, Ownable, Initi /** * @notice Check if last report is expired. * @param token The address of the token for which the CELO exchange rate is being reported. - * @return bool isExpired and the address of the last report + * @return isExpired + * @return The address of the last report. */ function isOldestReportExpired(address token) public view returns (bool, address) { require(token != address(0)); @@ -234,6 +238,7 @@ contract SortedOracles is ISortedOracles, ICeloVersionedContract, Ownable, Initi * @notice Returns the median rate. * @param token The address of the token for which the CELO exchange rate is being reported. * @return The median exchange rate for `token`. + * @return fixidity */ function medianRate(address token) external view returns (uint256, uint256) { return (rates[token].getMedianValue(), numRates(token) == 0 ? 0 : FIXED1_UINT); @@ -242,7 +247,9 @@ contract SortedOracles is ISortedOracles, ICeloVersionedContract, Ownable, Initi /** * @notice Gets all elements from the doubly linked list. * @param token The address of the token for which the CELO exchange rate is being reported. - * @return An unpacked list of elements from largest to smallest. + * @return keys Keys of nn unpacked list of elements from largest to smallest. + * @return values Values of an unpacked list of elements from largest to smallest. + * @return relations Relations of an unpacked list of elements from largest to smallest. */ function getRates(address token) external @@ -273,7 +280,9 @@ contract SortedOracles is ISortedOracles, ICeloVersionedContract, Ownable, Initi /** * @notice Gets all elements from the doubly linked list. * @param token The address of the token for which the CELO exchange rate is being reported. - * @return An unpacked list of elements from largest to smallest. + * @return keys Keys of nn unpacked list of elements from largest to smallest. + * @return values Values of an unpacked list of elements from largest to smallest. + * @return relations Relations of an unpacked list of elements from largest to smallest. */ function getTimestamps(address token) external diff --git a/packages/protocol/contracts/stability/StableToken.sol b/packages/protocol/contracts/stability/StableToken.sol index 5b27b8fc630..60f04e8d02b 100644 --- a/packages/protocol/contracts/stability/StableToken.sol +++ b/packages/protocol/contracts/stability/StableToken.sol @@ -93,7 +93,10 @@ contract StableToken is /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 2, 0, 1); diff --git a/packages/protocol/contracts/stability/StableTokenBRL.sol b/packages/protocol/contracts/stability/StableTokenBRL.sol index c2c9392a055..9bb75d5a5bc 100644 --- a/packages/protocol/contracts/stability/StableTokenBRL.sol +++ b/packages/protocol/contracts/stability/StableTokenBRL.sol @@ -12,7 +12,10 @@ contract StableTokenBRL is StableToken { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from StableToken.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 0); diff --git a/packages/protocol/contracts/stability/StableTokenEUR.sol b/packages/protocol/contracts/stability/StableTokenEUR.sol index c1cc01eec16..ce05a21f242 100644 --- a/packages/protocol/contracts/stability/StableTokenEUR.sol +++ b/packages/protocol/contracts/stability/StableTokenEUR.sol @@ -12,7 +12,10 @@ contract StableTokenEUR is StableToken { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from StableToken.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 1); diff --git a/packages/protocol/contracts/stability/StableTokenRegistry.sol b/packages/protocol/contracts/stability/StableTokenRegistry.sol index 61497796d27..f7d646888ef 100644 --- a/packages/protocol/contracts/stability/StableTokenRegistry.sol +++ b/packages/protocol/contracts/stability/StableTokenRegistry.sol @@ -14,7 +14,10 @@ contract StableTokenRegistry is Initializable, Ownable { /** * @notice Returns the storage, major, minor, and patch version of the contract. - * @return The storage, major, minor, and patch version of the contract. + * @return Storage version of the contract. + * @return Major version of the contract. + * @return Minor version of the contract. + * @return Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 0); @@ -46,7 +49,8 @@ contract StableTokenRegistry is Initializable, Ownable { /** * @notice Returns all the contract instances created. - * @return collection of stable token contracts. + * @return Collection of stable token contracts. + * @return Lengths of stable token contracts. */ function getContractInstances() external view returns (bytes memory, uint256[] memory) { uint256 totalLength = 0; diff --git a/packages/protocol/scripts/generate-stabletoken-files.ts b/packages/protocol/scripts/generate-stabletoken-files.ts index fd38fdc3823..990ca5b6749 100644 --- a/packages/protocol/scripts/generate-stabletoken-files.ts +++ b/packages/protocol/scripts/generate-stabletoken-files.ts @@ -15,7 +15,10 @@ contract StableToken${ticker} is StableToken { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from StableToken.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return storage Storage version of the contract. + * @return major Major version of the contract. + * @return minor Minor version of the contract. + * @return patch Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 0); @@ -39,7 +42,10 @@ contract Exchange${ticker} is Exchange { /** * @notice Returns the storage, major, minor, and patch version of the contract. * @dev This function is overloaded to maintain a distinct version from Exchange.sol. - * @return The storage, major, minor, and patch version of the contract. + * @return storage Storage version of the contract. + * @return major Major version of the contract. + * @return minor Minor version of the contract. + * @return patch Patch version of the contract. */ function getVersionNumber() external pure returns (uint256, uint256, uint256, uint256) { return (1, 1, 0, 0);