Address 5.4 audit documentation improvements (#5779)

Signed-off-by: Hadrien Croubois <hadrien.croubois@gmail.com>

contracts/governance/extensions/GovernorNoncesKeyed.sol

@@ -9,7 +9,7 @@ import {NoncesKeyed} from "../../utils/NoncesKeyed.sol";
 import {SignatureChecker} from "../../utils/cryptography/SignatureChecker.sol";
 
 /**
- * @dev An extension of {Governor} that extends existing nonce management to use {NoncesKeyed}, where the key is the first 192 bits of the `proposalId`.
+ * @dev An extension of {Governor} that extends existing nonce management to use {NoncesKeyed}, where the key is the low-order 192 bits of the `proposalId`.
  * This is useful for voting by signature while maintaining separate sequences of nonces for each proposal.
  *
  * NOTE: Traditional (un-keyed) nonces are still supported and can continue to be used as if this extension was not present.

contracts/utils/cryptography/signers/MultiSignerERC7913.sol

@@ -226,7 +226,7 @@ abstract contract MultiSignerERC7913 is AbstractSigner {
      *
      * Requirements:
      *
-     * * The `signatures` arrays must be at least as large as the `signers` arrays. Panics otherwise.
+     * * The `signatures` and `signers` arrays must be equal in length. Returns false otherwise.
      */
     function _validateSignatures(
         bytes32 hash,

contracts/utils/structs/EnumerableMap.sol

@@ -220,8 +220,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(UintToUintMap storage map) internal {
         clear(map._inner);
@@ -342,8 +343,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(UintToAddressMap storage map) internal {
         clear(map._inner);
@@ -464,8 +466,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(UintToBytes32Map storage map) internal {
         clear(map._inner);
@@ -586,8 +589,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(AddressToUintMap storage map) internal {
         clear(map._inner);
@@ -708,8 +712,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(AddressToAddressMap storage map) internal {
         clear(map._inner);
@@ -834,8 +839,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(AddressToBytes32Map storage map) internal {
         clear(map._inner);
@@ -960,8 +966,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(Bytes32ToUintMap storage map) internal {
         clear(map._inner);
@@ -1082,8 +1089,9 @@ library EnumerableMap {
     /**
      * @dev Removes all the entries from a map. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
-     * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function clear(Bytes32ToAddressMap storage map) internal {
         clear(map._inner);

contracts/utils/structs/EnumerableSet.sol

@@ -126,8 +126,9 @@ library EnumerableSet {
     /**
      * @dev Removes all the values from a set. O(n).
      *
-     * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+     * WARNING: This function has an unbounded cost that scales with set size. Developers should keep in mind that
-     * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
+     * using it may render the function uncallable if the set grows to the point where clearing it consumes too much
+     * gas to fit in a block.
      */
     function _clear(Set storage set) private {
         uint256 len = _length(set);

scripts/generate/templates/EnumerableMap.js

@@ -219,8 +219,9 @@ function remove(${name} storage map, ${key.type} key) internal returns (bool) {
 /**
  * @dev Removes all the entries from a map. O(n).
  *
- * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+ * WARNING: This function has an unbounded cost that scales with map size. Developers should keep in mind that
- * function uncallable if the map grows to the point where clearing it consumes too much gas to fit in a block.
+ * using it may render the function uncallable if the map grows to the point where clearing it consumes too much
+ * gas to fit in a block.
  */
 function clear(${name} storage map) internal {
     clear(map._inner);

scripts/generate/templates/EnumerableSet.js

@@ -130,8 +130,9 @@ function _remove(Set storage set, bytes32 value) private returns (bool) {
 /**
  * @dev Removes all the values from a set. O(n).
  *
- * WARNING: Developers should keep in mind that this function has an unbounded cost and using it may render the
+ * WARNING: This function has an unbounded cost that scales with set size. Developers should keep in mind that
- * function uncallable if the set grows to the point where clearing it consumes too much gas to fit in a block.
+ * using it may render the function uncallable if the set grows to the point where clearing it consumes too much
+ * gas to fit in a block.
  */
 function _clear(Set storage set) private {
     uint256 len = _length(set);