Fix lookup documentation in ERC20Votes and Checkpoints (OpenZeppelin#4218)

Co-authored-by: Hadrien Croubois <hadrien.croubois@gmail.com>

Author: ToonVanHove

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).

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.

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.