From 692d8c85a494f78b83aa4de44dcce4e3e63997d1 Mon Sep 17 00:00:00 2001 From: ToonVanHove Date: Fri, 5 May 2023 22:25:23 +0200 Subject: [PATCH] Fix lookup documentation in ERC20Votes and Checkpoints (#4218) Co-authored-by: Hadrien Croubois --- .../token/ERC20/extensions/ERC20Votes.sol | 2 +- contracts/utils/Checkpoints.sol | 24 +++++++++---------- scripts/generate/templates/Checkpoints.js | 10 ++++---- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/contracts/token/ERC20/extensions/ERC20Votes.sol b/contracts/token/ERC20/extensions/ERC20Votes.sol index d72d34f81..f44b89604 100644 --- a/contracts/token/ERC20/extensions/ERC20Votes.sol +++ b/contracts/token/ERC20/extensions/ERC20Votes.sol @@ -114,7 +114,7 @@ abstract contract ERC20Votes is ERC20Permit, IERC5805 { * @dev Lookup a value in a list of (sorted) checkpoints. */ function _checkpointsLookup(Checkpoint[] storage ckpts, uint256 timepoint) private view returns (uint256) { - // We run a binary search to look for the earliest checkpoint taken after `timepoint`. + // We run a binary search to look for the last (most recent) checkpoint taken before (or at) `timepoint`. // // Initially we check if the block is recent to narrow the search range. // During the loop, the index of the wanted checkpoint remains in the range [low-1, high). diff --git a/contracts/utils/Checkpoints.sol b/contracts/utils/Checkpoints.sol index 7d7905fd1..27da4b517 100644 --- a/contracts/utils/Checkpoints.sol +++ b/contracts/utils/Checkpoints.sol @@ -151,7 +151,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater than the search key, or `high` if there is none. + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. @@ -174,7 +174,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater or equal than the search key, or `high` if there is none. + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. @@ -225,7 +225,7 @@ library Checkpoints { } /** - * @dev Returns the value in the oldest checkpoint with key greater or equal than the search key, or zero if there is none. + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if there is none. */ function lowerLookup(Trace224 storage self, uint32 key) internal view returns (uint224) { uint256 len = self._checkpoints.length; @@ -234,7 +234,7 @@ library Checkpoints { } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. */ function upperLookup(Trace224 storage self, uint32 key) internal view returns (uint224) { uint256 len = self._checkpoints.length; @@ -243,7 +243,7 @@ library Checkpoints { } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. * * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high keys). */ @@ -324,7 +324,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater than the search key, or `high` if there is none. + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. @@ -347,7 +347,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater or equal than the search key, or `high` if there is none. + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. @@ -401,7 +401,7 @@ library Checkpoints { } /** - * @dev Returns the value in the oldest checkpoint with key greater or equal than the search key, or zero if there is none. + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if there is none. */ function lowerLookup(Trace160 storage self, uint96 key) internal view returns (uint160) { uint256 len = self._checkpoints.length; @@ -410,7 +410,7 @@ library Checkpoints { } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. */ function upperLookup(Trace160 storage self, uint96 key) internal view returns (uint160) { uint256 len = self._checkpoints.length; @@ -419,7 +419,7 @@ library Checkpoints { } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. * * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high keys). */ @@ -500,7 +500,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater than the search key, or `high` if there is none. + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. @@ -523,7 +523,7 @@ library Checkpoints { } /** - * @dev Return the index of the oldest checkpoint whose key is greater or equal than the search key, or `high` if there is none. + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or `high` if there is none. * `low` and `high` define a section where to do the search, with inclusive `low` and exclusive `high`. * * WARNING: `high` should not be greater than the array's length. diff --git a/scripts/generate/templates/Checkpoints.js b/scripts/generate/templates/Checkpoints.js index 18999682d..1d79031da 100644 --- a/scripts/generate/templates/Checkpoints.js +++ b/scripts/generate/templates/Checkpoints.js @@ -46,7 +46,7 @@ function push( } /** - * @dev Returns the value in the oldest checkpoint with key greater or equal than the search key, or zero if there is none. + * @dev Returns the value in the first (oldest) checkpoint with key greater or equal than the search key, or zero if there is none. */ function lowerLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) { uint256 len = self.${opts.checkpointFieldName}.length; @@ -55,7 +55,7 @@ function lowerLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} k } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. */ function upperLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} key) internal view returns (${opts.valueTypeName}) { uint256 len = self.${opts.checkpointFieldName}.length; @@ -64,7 +64,7 @@ function upperLookup(${opts.historyTypeName} storage self, ${opts.keyTypeName} k } /** - * @dev Returns the value in the most recent checkpoint with key lower or equal than the search key. + * @dev Returns the value in the last (most recent) checkpoint with key lower or equal than the search key. * * NOTE: This is a variant of {upperLookup} that is optimised to find "recent" checkpoint (checkpoints with high keys). */ @@ -227,7 +227,7 @@ function _insert( } /** - * @dev Return the index of the oldest checkpoint whose key is greater than the search key, or \`high\` if there is none. + * @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or \`high\` if there is none. * \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and exclusive \`high\`. * * WARNING: \`high\` should not be greater than the array's length. @@ -250,7 +250,7 @@ function _upperBinaryLookup( } /** - * @dev Return the index of the oldest checkpoint whose key is greater or equal than the search key, or \`high\` if there is none. + * @dev Return the index of the first (oldest) checkpoint with key is greater or equal than the search key, or \`high\` if there is none. * \`low\` and \`high\` define a section where to do the search, with inclusive \`low\` and exclusive \`high\`. * * WARNING: \`high\` should not be greater than the array's length.