@1inch/solidity-utils 4.0.0 → 4.2.0

package/contracts/libraries/AddressSet.sol

@@ -4,50 +4,79 @@ pragma solidity ^0.8.0;
 
 import "./AddressArray.sol";
 
-/** @title Library that is using AddressArray library for AddressArray.Data
- * and allows Set operations on address storage data:
- * 1. add
- * 2. remove
- * 3. contains
+/**
+ * @title AddressSet
+ * @notice Library for managing sets of addresses, allowing operations such as add, remove, and contains.
+ * Utilizes the AddressArray library for underlying data storage.
  */
 library AddressSet {
     using AddressArray for AddressArray.Data;
 
     uint256 internal constant _NULL_INDEX = type(uint256).max;
 
-    /// @dev Data struct from AddressArray.Data items and lookup mapping address => index in data array.
+    /**
+     * @dev Data struct from AddressArray.Data items
+     * and lookup mapping address => index in data array.
+     */
     struct Data {
         AddressArray.Data items;
         mapping(address => uint256) lookup;
     }
 
-    /// @dev Length of data storage.
+    /**
+     * @notice Determines the number of addresses in the set.
+     * @param s The set of addresses.
+     * @return The number of addresses in the set.
+     */
     function length(Data storage s) internal view returns (uint256) {
         return s.items.length();
     }
 
-    /// @dev Returns data item from `s` storage at `index`.
+    /**
+     * @notice Retrieves the address at a specified index in the set.
+     * @param s The set of addresses.
+     * @param index The index of the address to retrieve.
+     * @return The address at the specified index.
+     */
     function at(Data storage s, uint256 index) internal view returns (address) {
         return s.items.at(index);
     }
 
-    /// @dev Returns true if storage `s` has `item`.
+    /**
+     * @notice Checks if the set contains the specified address.
+     * @param s The set of addresses.
+     * @param item The address to check for.
+     * @return True if the set contains the address, false otherwise.
+     */
     function contains(Data storage s, address item) internal view returns (bool) {
         uint256 index = s.lookup[item];
         return index != 0 && index != _NULL_INDEX;
     }
 
-    /// @dev Returns list of addresses from storage `s`.
+    /**
+     * @notice Returns list of addresses from storage `s`.
+     * @param s The set of addresses.
+     * @return The array of addresses stored in `s`.
+     */
     function get(Data storage s) internal view returns (address[] memory) {
         return s.items.get();
     }
 
-    /// @dev Puts list of addresses from `s` storage into `output` array.
+    /**
+     * @notice Puts list of addresses from `s` storage into `output` array.
+     * @param s The set of addresses.
+     * @return The provided output array filled with addresses.
+     */
     function get(Data storage s, address[] memory input) internal view returns (address[] memory) {
         return s.items.get(input);
     }
 
-    /// @dev Adds `item` into storage `s` and returns true if successful.
+    /**
+     * @notice Adds an address to the set if it is not already present.
+     * @param s The set of addresses.
+     * @param item The address to add.
+     * @return True if the address was added to the set, false if it was already present.
+     */
     function add(Data storage s, address item) internal returns (bool) {
         uint256 index = s.lookup[item];
         if (index != 0 && index != _NULL_INDEX) {
@@ -57,7 +86,12 @@ library AddressSet {
         return true;
     }
 
-    /// @dev Removes `item` from storage `s` and returns true if successful.
+    /**
+     * @notice Removes an address from the set if it exists.
+     * @param s The set of addresses.
+     * @param item The address to remove.
+     * @return True if the address was removed from the set, false if it was not found.
+     */
     function remove(Data storage s, address item) internal returns (bool) {
         uint256 index = s.lookup[item];
         s.lookup[item] = _NULL_INDEX;
@@ -75,7 +109,11 @@ library AddressSet {
         return true;
     }
 
-    /// @dev Erases set from storage `s` and returns all removed items
+    /**
+     * @notice Erases set from storage `s`.
+     * @param s The set of addresses.
+     * @return items All removed items.
+     */
     function erase(Data storage s) internal returns(address[] memory items) {
         items = s.items.get();
         uint256 len = items.length;

package/contracts/libraries/BySigTraits.sol

@@ -2,14 +2,25 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title BySigTraits
+ * @notice Provides utility functions for decoding and working with `BySig` call traits encoded in a single `uint256` value.
+ * @dev This library allows for the compact representation and manipulation of various call traits such as nonce type,
+ * deadline, relayer allowance, and nonce value using bit manipulation techniques.
+ */
 library BySigTraits {
+    /// @notice Thrown when an invalid nonce type is encountered.
     error WrongNonceType();
 
-    // 2 bits for type
-    // 6 bits reserved for future use
-    // 40 bits for deadline
-    // 80 bits for relayer address lower bits
-    // 128 bits for nonce value
+    /**
+     * @dev Represents the encoded traits of a call, packed within a single `uint256`.
+     * The encoding is as follows:
+     * [255-254] -   2 bits - Nonce type (e.g., Account, Selector, Unique).
+     * [253-248] -   6 bits - Reserved for future use.
+     * [247-208] -  40 bits - Deadline (Unix timestamp at which the call becomes invalid).
+     * [207-128] -  80 bits - Relayer address's lower bits. A value of 0 indicates that any relayer is allowed.
+     * [127-0]   - 128 bits - Nonce value (used for ensuring calls are executed in order and not replayed).
+     */
     type Value is uint256;
 
     enum NonceType {
@@ -25,21 +36,42 @@ library BySigTraits {
     uint256 constant internal RELAYER_BIT_MASK = (1 << 80) - 1;
     uint256 constant internal NONCE_MASK = (1 << 128) - 1;
 
+    /**
+     * @notice Decodes and returns the nonce type from the traits.
+     * @param traits The encoded call traits.
+     * @return The decoded nonce type as an enum.
+     */
     function nonceType(Value traits) internal pure returns(NonceType) {
         uint256 _type = Value.unwrap(traits) >> TYPE_BIT_SHIFT;
         if (_type > uint256(NonceType.Unique)) revert WrongNonceType();
         return NonceType(_type);
     }
 
+    /**
+     * @notice Decodes and returns the deadline from the traits.
+     * @param traits The encoded call traits.
+     * @return The decoded deadline timestamp.
+     */
     function deadline(Value traits) internal pure returns(uint256) {
         return (Value.unwrap(traits) >> DEADLINE_BIT_SHIFT) & DEADLINE_BIT_MASK;
     }
 
+    /**
+     * @notice Checks if a given relayer address is allowed to relay the call based on the traits.
+     * @param traits The encoded call traits.
+     * @param relayer The address of the relayer to check.
+     * @return True if the relayer is allowed, false otherwise.
+     */
     function isRelayerAllowed(Value traits, address relayer) internal pure returns(bool) {
         uint256 relayerBits = (Value.unwrap(traits) >> RELAYER_BIT_SHIFT) & RELAYER_BIT_MASK;
         return relayerBits == 0 || (uint160(relayer) & RELAYER_BIT_MASK) == relayerBits;
     }
 
+    /**
+     * @notice Decodes and returns the nonce value from the traits.
+     * @param traits The encoded call traits.
+     * @return The decoded nonce value.
+     */
     function nonce(Value traits) internal pure returns(uint256) {
         return Value.unwrap(traits) & NONCE_MASK;
     }

package/contracts/libraries/BytesMemory.sol

@@ -3,7 +3,8 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title A library for operating on bytes memory slices without copying.
+ * @title BytesMemory
+ * @notice A library for operating on bytes memory slices without copying.
  */
 library BytesMemory {
     error OutOfBounds();

package/contracts/libraries/BytesStorage.sol

@@ -3,7 +3,8 @@
 pragma solidity ^0.8.0;
 
 /**
- * @title A library for operating on bytes storage slices.
+ * @title BytesStorage
+ * @notice A library for operating on bytes storage slices.
  */
 library BytesStorage {
     error OutOfBounds();

package/contracts/libraries/ECDSA.sol

@@ -4,6 +4,10 @@ pragma solidity ^0.8.0;
 
 import "@openzeppelin/contracts/interfaces/IERC1271.sol";
 
+/**
+ * @title ECDSA signature operations
+ * @notice Provides functions for recovering addresses from signatures and verifying signatures, including support for EIP-2098 compact signatures.
+ */
 library ECDSA {
     // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature
     // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines
@@ -18,6 +22,15 @@ library ECDSA {
     uint256 private constant _COMPACT_S_MASK = 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;
     uint256 private constant _COMPACT_V_SHIFT = 255;
 
+    /**
+     * @notice Recovers the signer's address from the signature.
+     * @dev Recovers the address that has signed a hash with `(v, r, s)` signature.
+     * @param hash The keccak256 hash of the data signed.
+     * @param v The recovery byte of the signature.
+     * @param r The first 32 bytes of the signature.
+     * @param s The second 32 bytes of the signature.
+     * @return signer The address of the signer.
+     */
     function recover(
         bytes32 hash,
         uint8 v,
@@ -39,6 +52,14 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Recovers the signer's address from the signature using `r` and `vs` components.
+     * @dev Recovers the address that has signed a hash with `r` and `vs`, where `vs` combines `v` and `s`.
+     * @param hash The keccak256 hash of the data signed.
+     * @param r The first 32 bytes of the signature.
+     * @param vs The combined `v` and `s` values of the signature.
+     * @return signer The address of the signer.
+     */
     function recover(
         bytes32 hash,
         bytes32 r,
@@ -60,6 +81,12 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Recovers the signer's address from a hash and a signature.
+     * @param hash The keccak256 hash of the signed data.
+     * @param signature The full signature from which the signer will be recovered.
+     * @return signer The address of the signer.
+     */
     /// @dev WARNING!!!
     /// There is a known signature malleability issue with two representations of signatures!
     /// Even though this function is able to verify both standard 65-byte and compact 64-byte EIP-2098 signatures
@@ -102,6 +129,14 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Verifies the signature for a hash, either by recovering the signer or using EIP-1271's `isValidSignature` function.
+     * @dev Attempts to recover the signer's address from the signature; if the address is non-zero, checks if it's valid according to EIP-1271.
+     * @param signer The address to validate the signature against.
+     * @param hash The hash of the signed data.
+     * @param signature The signature to verify.
+     * @return success True if the signature is verified, false otherwise.
+     */
     function recoverOrIsValidSignature(
         address signer,
         bytes32 hash,
@@ -114,6 +149,16 @@ library ECDSA {
         return isValidSignature(signer, hash, signature);
     }
 
+    /**
+     * @notice Verifies the signature for a hash, either by recovering the signer or using EIP-1271's `isValidSignature` function.
+     * @dev Attempts to recover the signer's address from the signature; if the address is non-zero, checks if it's valid according to EIP-1271.
+     * @param signer The address to validate the signature against.
+     * @param hash The hash of the signed data.
+     * @param v The recovery byte of the signature.
+     * @param r The first 32 bytes of the signature.
+     * @param s The second 32 bytes of the signature.
+     * @return success True if the signature is verified, false otherwise.
+     */
     function recoverOrIsValidSignature(
         address signer,
         bytes32 hash,
@@ -128,6 +173,15 @@ library ECDSA {
         return isValidSignature(signer, hash, v, r, s);
     }
 
+    /**
+     * @notice Verifies the signature for a hash, either by recovering the signer or using EIP-1271's `isValidSignature` function.
+     * @dev Attempts to recover the signer's address from the signature; if the address is non-zero, checks if it's valid according to EIP-1271.
+     * @param signer The address to validate the signature against.
+     * @param hash The hash of the signed data.
+     * @param r The first 32 bytes of the signature.
+     * @param vs The combined `v` and `s` values of the signature.
+     * @return success True if the signature is verified, false otherwise.
+     */
     function recoverOrIsValidSignature(
         address signer,
         bytes32 hash,
@@ -141,6 +195,15 @@ library ECDSA {
         return isValidSignature(signer, hash, r, vs);
     }
 
+    /**
+     * @notice Verifies the signature for a given hash, attempting to recover the signer's address or validates it using EIP-1271 for 65-byte signatures.
+     * @dev Attempts to recover the signer's address from the signature. If the address is a contract, checks if the signature is valid according to EIP-1271.
+     * @param signer The expected signer's address.
+     * @param hash The keccak256 hash of the signed data.
+     * @param r The first 32 bytes of the signature.
+     * @param vs The last 32 bytes of the signature, with the last byte being the recovery id.
+     * @return success True if the signature is valid, false otherwise.
+     */
     function recoverOrIsValidSignature65(
         address signer,
         bytes32 hash,
@@ -154,6 +217,14 @@ library ECDSA {
         return isValidSignature65(signer, hash, r, vs);
     }
 
+    /**
+     * @notice Validates a signature for a hash using EIP-1271, if `signer` is a contract.
+     * @dev Makes a static call to `signer` with `isValidSignature` function selector from EIP-1271.
+     * @param signer The address of the signer to validate against, which could be an EOA or a contract.
+     * @param hash The hash of the signed data.
+     * @param signature The signature to validate.
+     * @return success True if the signature is valid according to EIP-1271, false otherwise.
+     */
     function isValidSignature(
         address signer,
         bytes32 hash,
@@ -176,6 +247,16 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Validates a signature for a hash using EIP-1271, if `signer` is a contract.
+     * @dev Makes a static call to `signer` with `isValidSignature` function selector from EIP-1271.
+     * @param signer The address of the signer to validate against, which could be an EOA or a contract.
+     * @param hash The hash of the signed data.
+     * @param v The recovery byte of the signature.
+     * @param r The first 32 bytes of the signature.
+     * @param s The second 32 bytes of the signature.
+     * @return success True if the signature is valid according to EIP-1271, false otherwise.
+     */
     function isValidSignature(
         address signer,
         bytes32 hash,
@@ -200,6 +281,15 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Validates a signature for a hash using EIP-1271, if `signer` is a contract.
+     * @dev Makes a static call to `signer` with `isValidSignature` function selector from EIP-1271.
+     * @param signer The address of the signer to validate against, which could be an EOA or a contract.
+     * @param hash The hash of the signed data.
+     * @param r The first 32 bytes of the signature.
+     * @param vs The last 32 bytes of the signature, with the last byte being the recovery id.
+     * @return success True if the signature is valid according to EIP-1271, false otherwise.
+     */
     function isValidSignature(
         address signer,
         bytes32 hash,
@@ -224,6 +314,14 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Verifies if a 65-byte signature is valid for a given hash, according to EIP-1271.
+     * @param signer The address of the signer to validate against, which could be an EOA or a contract.
+     * @param hash The hash of the signed data.
+     * @param r The first 32 bytes of the signature.
+     * @param vs The combined `v` (recovery id) and `s` component of the signature, packed into the last 32 bytes.
+     * @return success True if the signature is valid according to EIP-1271, false otherwise.
+     */
     function isValidSignature65(
         address signer,
         bytes32 hash,
@@ -249,6 +347,12 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Generates a hash compatible with Ethereum's signed message format.
+     * @dev Prepends the hash with Ethereum's message prefix before hashing it.
+     * @param hash The hash of the data to sign.
+     * @return res The Ethereum signed message hash.
+     */
     function toEthSignedMessageHash(bytes32 hash) internal pure returns (bytes32 res) {
         // 32 is the length in bytes of hash, enforced by the type signature above
         // return keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", hash));
@@ -259,6 +363,13 @@ library ECDSA {
         }
     }
 
+    /**
+     * @notice Generates an EIP-712 compliant hash.
+     * @dev Encodes the domain separator and the struct hash according to EIP-712.
+     * @param domainSeparator The EIP-712 domain separator.
+     * @param structHash The EIP-712 struct hash.
+     * @return res The EIP-712 compliant hash.
+     */
     function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32 res) {
         // return keccak256(abi.encodePacked("\x19\x01", domainSeparator, structHash));
         assembly ("memory-safe") { // solhint-disable-line no-inline-assembly

package/contracts/libraries/RevertReasonForwarder.sol

@@ -2,9 +2,15 @@
 
 pragma solidity ^0.8.0;
 
-/// @title Revert reason forwarder.
+/**
+ * @title RevertReasonForwarder
+ * @notice Provides utilities for forwarding and retrieving revert reasons from failed external calls.
+ */
 library RevertReasonForwarder {
-    /// @dev Forwards latest externall call revert.
+    /**
+     * @dev Forwards the revert reason from the latest external call.
+     * This method allows propagating the revert reason of a failed external call to the caller.
+     */
     function reRevert() internal pure {
         // bubble up revert reason from latest external call
         assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
@@ -14,7 +20,11 @@ library RevertReasonForwarder {
         }
     }
 
-    /// @dev Returns latest external call revert reason.
+    /**
+     * @dev Retrieves the revert reason from the latest external call.
+     * This method enables capturing the revert reason of a failed external call for inspection or processing.
+     * @return reason The latest external call revert reason.
+     */
     function reReason() internal pure returns (bytes memory reason) {
         assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
             reason := mload(0x40)

package/contracts/libraries/RevertReasonParser.sol

@@ -4,7 +4,9 @@ pragma solidity ^0.8.0;
 
 import "./StringUtil.sol";
 
-/** @title Library that allows to parse unsuccessful arbitrary calls revert reasons.
+/**
+ * @title RevertReasonParser
+ * @notice Library that allows to parse unsuccessful arbitrary calls revert reasons.
  * See https://solidity.readthedocs.io/en/latest/control-structures.html#revert for details.
  * Note that we assume revert reason being abi-encoded as Error(string) so it may fail to parse reason
  * if structured reverts appear in the future.
@@ -20,7 +22,14 @@ library RevertReasonParser {
     bytes4 private constant _ERROR_SELECTOR = bytes4(keccak256("Error(string)"));
     bytes4 private constant _PANIC_SELECTOR = bytes4(keccak256("Panic(uint256)"));
 
-    /// @dev Parses error `data` and returns actual with `prefix`.
+    /**
+     * @dev Parses revert reason from failed calls, returning it with a `prefix`.
+     * Handles standard `Error(string)` and `Panic(uint256)` formats, defaulting to `Unknown(data)` for unrecognized patterns.
+     *
+     * @param data The revert data to parse.
+     * @param prefix String to add before the parsed reason for context.
+     * @return The formatted revert reason.
+     */
     function parse(bytes memory data, string memory prefix) internal pure returns (string memory) {
         // https://solidity.readthedocs.io/en/latest/control-structures.html#revert
         // We assume that revert reason is abi-encoded as Error(string)

package/contracts/libraries/SafeERC20.sol

@@ -282,7 +282,7 @@ library SafeERC20 {
 
     /**
      * @notice The function attempts to call the permit function on a given ERC20 token.
-     * @dev The function is designed to support a variety of permit functions, namely: IERC20Permit, IDaiLikePermit, and IPermit2.
+     * @dev The function is designed to support a variety of permit functions, namely: IERC20Permit, IDaiLikePermit, IERC7597Permit and IPermit2.
      * It accommodates both Compact and Full formats of these permit types.
      * Please note, it is expected that the `expiration` parameter for the compact Permit2 and the `deadline` parameter
      * for the compact Permit are to be incremented by one before invoking this function. This approach is motivated by

package/contracts/libraries/StringUtil.sol

@@ -2,18 +2,36 @@
 
 pragma solidity ^0.8.0;
 
-/// @title Library with gas-efficient string operations
+/**
+ * @title StringUtil
+ * @dev Library with gas-efficient string operations.
+ */
 library StringUtil {
+    /**
+     * @notice Converts a uint256 value to its hexadecimal string representation.
+     * @param value The uint256 value to convert.
+     * @return The hexadecimal string representation of the input value.
+     */
     function toHex(uint256 value) internal pure returns (string memory) {
         return toHex(abi.encodePacked(value));
     }
 
+    /**
+     * @notice Converts an address to its hexadecimal string representation.
+     * @param value The address to convert.
+     * @return The hexadecimal string representation of the input address.
+     */
     function toHex(address value) internal pure returns (string memory) {
         return toHex(abi.encodePacked(value));
     }
 
-    /// @dev this is the assembly adaptation of highly optimized toHex16 code from Mikhail Vladimirov
-    /// https://stackoverflow.com/a/69266989
+    /**
+     * @dev Converts arbitrary bytes to their hexadecimal string representation.
+     * This is an assembly adaptation of highly optimized toHex16 code by Mikhail Vladimirov.
+     * Reference: https://stackoverflow.com/a/69266989
+     * @param data The bytes to be converted to hexadecimal string.
+     * @return result The hexadecimal string representation of the input bytes.
+     */
     function toHex(bytes memory data) internal pure returns (string memory result) {
         assembly ("memory-safe") { // solhint-disable-line no-inline-assembly
             function _toHex16(input) -> output {

package/contracts/libraries/UniERC20.sol

@@ -8,7 +8,11 @@ import "../interfaces/IERC20MetadataUppercase.sol";
 import "./SafeERC20.sol";
 import "./StringUtil.sol";
 
-/// @title Library, which allows usage of ETH as ERC20 and ERC20 itself. Uses SafeERC20 library for ERC20 interface.
+/**
+ * @title UniERC20
+ * @dev Library to abstract the handling of ETH and ERC20 tokens, enabling unified interaction with both. It allows usage of ETH as ERC20.
+ * Utilizes SafeERC20 for ERC20 interactions and provides additional utility functions.
+ */
 library UniERC20 {
     using SafeERC20 for IERC20;
 
@@ -23,12 +27,21 @@ library UniERC20 {
     IERC20 private constant _ETH_ADDRESS = IERC20(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE);
     IERC20 private constant _ZERO_ADDRESS = IERC20(address(0));
 
-    /// @dev Returns true if `token` is ETH.
+    /**
+     * @dev Determines if the specified token is ETH.
+     * @param token The token to check.
+     * @return bool True if the token is ETH, false otherwise.
+     */
     function isETH(IERC20 token) internal pure returns (bool) {
         return (token == _ZERO_ADDRESS || token == _ETH_ADDRESS);
     }
 
-    /// @dev Returns `account` ERC20 `token` balance.
+    /**
+     * @dev Retrieves the balance of the specified token for an account.
+     * @param token The token to query the balance of.
+     * @param account The address of the account.
+     * @return uint256 The balance of the token for the specified account.
+     */
     function uniBalanceOf(IERC20 token, address account) internal view returns (uint256) {
         if (isETH(token)) {
             return account.balance;
@@ -37,8 +50,13 @@ library UniERC20 {
         }
     }
 
-    /// @dev `token` transfer `to` `amount`.
-    /// Note that this function does nothing in case of zero amount.
+    /**
+     * @dev Transfers a specified amount of the token to a given address.
+     * Note: Does nothing if the amount is zero.
+     * @param token The token to transfer.
+     * @param to The address to transfer the token to.
+     * @param amount The amount of the token to transfer.
+     */
     function uniTransfer(
         IERC20 token,
         address payable to,
@@ -56,8 +74,14 @@ library UniERC20 {
         }
     }
 
-    /// @dev `token` transfer `from` `to` `amount`.
-    /// Note that this function does nothing in case of zero amount.
+    /**
+     * @dev Transfers a specified amount of the token from one address to another.
+     * Note: Does nothing if the amount is zero.
+     * @param token The token to transfer.
+     * @param from The address to transfer the token from.
+     * @param to The address to transfer the token to.
+     * @param amount The amount of the token to transfer.
+     */
     function uniTransferFrom(
         IERC20 token,
         address payable from,
@@ -83,17 +107,31 @@ library UniERC20 {
         }
     }
 
-    /// @dev Returns `token` symbol from ERC20 metadata.
+    /**
+     * @dev Retrieves the symbol from ERC20 metadata of the specified token.
+     * @param token The token to retrieve the symbol of.
+     * @return string The symbol of the token.
+     */
     function uniSymbol(IERC20 token) internal view returns (string memory) {
         return _uniDecode(token, IERC20Metadata.symbol.selector, IERC20MetadataUppercase.SYMBOL.selector);
     }
 
-    /// @dev Returns `token` name from ERC20 metadata.
+    /**
+     * @dev Retrieves the name from ERC20 metadata of the specified token.
+     * @param token The token to retrieve the name of.
+     * @return string The name of the token.
+     */
     function uniName(IERC20 token) internal view returns (string memory) {
         return _uniDecode(token, IERC20Metadata.name.selector, IERC20MetadataUppercase.NAME.selector);
     }
 
-    /// @dev Reverts if `token` is ETH, otherwise performs ERC20 forceApprove.
+    /**
+     * @dev forceApprove the specified amount of the token to a given address.
+     * Reverts if the token is ETH.
+     * @param token The token to approve.
+     * @param to The address to approve the token to.
+     * @param amount The amount of the token to approve.
+     */
     function uniApprove(
         IERC20 token,
         address to,
@@ -104,8 +142,15 @@ library UniERC20 {
         token.forceApprove(to, amount);
     }
 
-    /// @dev 20K gas is provided to account for possible implementations of name/symbol
-    /// (token implementation might be behind proxy or store the value in storage)
+    /**
+     * @dev Internal function to decode token metadata (name or symbol).
+     * 20K gas is provided to account for possible implementations of name/symbol
+     * (token implementation might be behind proxy or store the value in storage)
+     * @param token The token to decode metadata for.
+     * @param lowerCaseSelector The selector for the lowercase metadata function.
+     * @param upperCaseSelector The selector for the uppercase metadata function.
+     * @return result The decoded metadata value.
+     */
     function _uniDecode(
         IERC20 token,
         bytes4 lowerCaseSelector,