Update documentation

src/ERC6538Registry.sol

@@ -17,20 +17,26 @@ contract ERC6538Registry is IERC6538Registry {
   /// @dev `nonce` will be incremented after each valid `registerKeysOnBehalf` call.
   mapping(address user => uint256 nonce) public nonceOf;
 
-  /// @dev EIP-712 Type hash used in `registerKeysOnBehalf`
+  /// @dev EIP-712 Type hash used in `registerKeysOnBehalf`.
   bytes32 public constant TYPE_HASH =
     keccak256("EIP712Domain(string name,string version,uint256 chainId,address registryContract)");
 
-  // Cache the domain separator as an immutable value, but also store the chain id that it
-  // corresponds to, in order to invalidate the cached domain separator if the chain id changes.
+  /// @dev Cache the domain separator as an immutable value.
   bytes32 private immutable _cachedDomainSeparator;
+  /// @dev Store the chain id that `_cachedDomainSeparator` corresponds to, in order to invalidate
+  /// the cached domain separator if the chain id changes.
   uint256 private immutable _cachedChainId;
+  /// @dev Cache the address of this contract as an immutable value.
   address private immutable _cachedThis;
 
+  /// @dev Cache the hash of the name as an immutable value.
   bytes32 private immutable _hashedName;
+  /// @dev Cache the hash of the version as immutable value.
   bytes32 private immutable _hashedVersion;
 
+  /// @dev Name of the registry.
   string private _name;
+  /// @dev Version of the registry.
   string private _version;
 
   enum RecoverError {
@@ -98,23 +104,25 @@ contract ERC6538Registry is IERC6538Registry {
       keccak256(abi.encode(TYPE_HASH, _hashedName, _hashedVersion, block.chainid, address(this)));
   }
 
-  /// @notice this function returns the hash of the fully encoded EIP712 message for this domain.
+  /// @notice Returns the hash of the fully encoded EIP712 message for this domain.
   /// @dev The following code is from OpenZeppelin's `EIP712.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/EIP712.sol
+  /// @param structHash The hash of the struct containing the message data, as defined in
+  /// https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct
   function _hashTypedDataV4(bytes32 structHash) internal view virtual returns (bytes32) {
     return toTypedDataHash(_domainSeparatorV4(), structHash);
   }
 
   /// @dev Returns the keccak256 digest of an EIP-712 typed data (ERC-191 version `0x01`).
-  ///
-  /// The digest is calculated from a `domainSeparator` and a `structHash`, by prefixing them with
-  /// `\x19\x01` and hashing the result. It corresponds to the hash signed by the
+  /// @dev The digest is calculated from a `domainSeparator` and a `structHash`, by prefixing them
+  /// with `\x19\x01` and hashing the result. It corresponds to the hash signed by the
   /// https://eips.ethereum.org/EIPS/eip-712[`eth_signTypedData`] JSON-RPC method as part of
   /// EIP-712.
-  ///
-  /// See {ECDSA-recover}.
   /// @dev The following code is from OpenZeppelin's `MessageHashUtils.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/MessageHashUtils.sol
+  /// @param domainSeparator The domain separator returned by `_domainSeparatorV4`.
+  /// @param structHash The hash of the struct containing the message data, as defined in
+  /// https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct
   function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash)
     internal
     pure
@@ -132,9 +140,12 @@ contract ERC6538Registry is IERC6538Registry {
 
   /// @notice Checks if a signature is valid for a given signer and data hash. If the signer is a
   /// smart contract, the signature is validated against that smart contract using ERC1271,
-  /// otherwise it's validated using `ECDSA.recover`.
+  /// otherwise it's validated using `tryRecover`.
   /// @dev The following code is from OpenZeppelin's `SignatureChecker.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/SignatureChecker.sol
+  /// @param signer The address that should have signed the message data.
+  /// @param hash The digest of message data.
+  /// @param signature The signature provided by the registrant.
   function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature)
     internal
     view
@@ -149,6 +160,9 @@ contract ERC6538Registry is IERC6538Registry {
   /// validated against the signer smart contract using ERC1271.
   /// @dev The following code is from OpenZeppelin's `SignatureChecker.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/SignatureChecker.sol
+  /// @param signer The address that should have signed the message data.
+  /// @param hash The digest of message data.
+  /// @param signature The signature provided by the registrant.
   function isValidERC1271SignatureNow(address signer, bytes32 hash, bytes memory signature)
     internal
     view
@@ -164,6 +178,8 @@ contract ERC6538Registry is IERC6538Registry {
 
   /// @dev The following code is from OpenZeppelin's `ECDSA.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/ECDSA.sol
+  /// @param hash The digest of message data.
+  /// @param signature The signature provided by the registrant.
   function tryRecover(bytes32 hash, bytes memory signature)
     internal
     pure
@@ -173,9 +189,6 @@ contract ERC6538Registry is IERC6538Registry {
       bytes32 r;
       bytes32 s;
       uint8 v;
-      // ecrecover takes the signature parameters, and the only way to get them
-      // currently is to use assembly.
-      /// @solidity memory-safe-assembly
       assembly {
         r := mload(add(signature, 0x20))
         s := mload(add(signature, 0x40))
@@ -187,36 +200,30 @@ contract ERC6538Registry is IERC6538Registry {
     }
   }
 
-  /// @notice Overload of {ECDSA-tryRecover} that receives the `v`, `r` and `s` signature fields
-  /// separately.
+  /// @notice Recover the signer's address using `v`, `r` and `s` signature fields.
   /// @dev The following code is from OpenZeppelin's `ECDSA.sol` file. Permalink:
   /// https://github.com/OpenZeppelin/openzeppelin-contracts/blob/e70a0118ef10773457f670671baefad2c5ea610d/contracts/utils/cryptography/ECDSA.sol
   function tryRecover(bytes32 hash, uint8 v, bytes32 r, bytes32 s)
     internal
     pure
     returns (address, RecoverError, bytes32)
   {
-    // 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
-    // the valid range for s in (301): 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27,
-    // 28}. Most
-    // signatures from current libraries generate a unique signature with an s-value in the lower
-    // half order.
-    //
-    // If your library generates malleable signatures, such as s-values in the upper range,
-    // calculate a new s-value
-    // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from
-    // 27 to 28 or
-    // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to
-    // v to accept
-    // these malleable signatures as well.
+    /// 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 the valid range for s in (301):
+    /// 0 < s < secp256k1n ÷ 2 + 1, and for v in (302): v ∈ {27, 28}. Most signatures from
+    /// current libraries generate a unique signature with an s-value in the lower half order.
+
+    /// If your library generates malleable signatures, such as s-values in the upper range,
+    /// calculate a new s-value with
+    /// 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27
+    /// to 28 or vice versa. If your library also generates signatures with 0/1 for v instead 27/28,
+    /// add 27 to v to accept these malleable signatures as well.
     if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {
       return (address(0), RecoverError.InvalidSignatureS, s);
     }
 
-    // If the signature is valid (and not malleable), return the signer address
+    /// If the signature is valid (and not malleable), return the signer address
     address signer = ecrecover(hash, v, r, s);
     if (signer == address(0)) return (address(0), RecoverError.InvalidSignature, bytes32(0));