refactor(wiki): add docstrings to ISCTypes and ISCUtil interface func…

…tions
iotaledger · Jul 9, 2024 · a442ba1 · a442ba1
1 parent f6f5886
commit a442ba1
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 2 deletions.
diff --git a/packages/vm/core/evm/iscmagic/ISCTypes.sol b/packages/vm/core/evm/iscmagic/ISCTypes.sol
@@ -142,12 +142,23 @@ struct ISCTokenProperties {
 }
 
 library ISCTypes {
+    /**
+     * @dev Get the type of an L1 address.
+     * @param addr The L1 address.
+     * @return The type of the L1 address.
+     */
     function L1AddressType(
         L1Address memory addr
     ) internal pure returns (uint8) {
         return uint8(addr.data[0]);
     }
 
+    /**
+     * @dev Create a new Ethereum AgentID.
+     * @param addr The Ethereum address.
+     * @param iscChainID The ISC chain ID.
+     * @return The new ISCAgentID.
+     */
     function newEthereumAgentID(
         address addr,
         ISCChainID iscChainID
@@ -170,6 +181,11 @@ library ISCTypes {
         return r;
     }
 
+    /**
+     * @dev Create a new L1 AgentID.
+     * @param l1Addr The L1 address.
+     * @return The new ISCAgentID.
+     */
     function newL1AgentID(
         bytes memory l1Addr
     ) internal pure returns (ISCAgentID memory) {
@@ -188,17 +204,32 @@ library ISCTypes {
         return r;
     }
 
+    /**
+     * @dev Check if an ISCAgentID is of Ethereum type.
+     * @param a The ISCAgentID to check.
+     * @return True if the ISCAgentID is of Ethereum type, false otherwise.
+     */
     function isEthereum(ISCAgentID memory a) internal pure returns (bool) {
         return uint8(a.data[0]) == ISCAgentIDKindEthereumAddress;
     }
 
+    /**
+     * @dev Get the Ethereum address from an ISCAgentID.
+     * @param a The ISCAgentID.
+     * @return The Ethereum address.
+     */
     function ethAddress(ISCAgentID memory a) internal pure returns (address) {
         bytes memory b = new bytes(20);
         //offset of 33 (kind byte + chainID)
         for (uint i = 0; i < 20; i++) b[i] = a.data[i + 33];
         return address(uint160(bytes20(b)));
     }
 
+    /**
+     * @dev Get the chain ID from an ISCAgentID.
+     * @param a The ISCAgentID.
+     * @return The ISCChainID.
+     */
     function chainID(ISCAgentID memory a) internal pure returns (ISCChainID) {
         bytes32 out;
         for (uint i = 0; i < 32; i++) {
@@ -208,10 +239,21 @@ library ISCTypes {
         return ISCChainID.wrap(out);
     }
 
+    /**
+     * @notice Convert a token ID to an NFTID.
+     * @param tokenID The token ID.
+     * @return The NFTID.
+     */
     function asNFTID(uint256 tokenID) internal pure returns (NFTID) {
         return NFTID.wrap(bytes32(tokenID));
     }
 
+    /**
+     * @dev Check if an NFT is part of a given collection.
+     * @param nft The NFT to check.
+     * @param collectionId The collection ID to check against.
+     * @return True if the NFT is part of the collection, false otherwise.
+     */
     function isInCollection(
         ISCNFT memory nft,
         NFTID collectionId

diff --git a/packages/vm/core/evm/iscmagic/ISCUtil.sol b/packages/vm/core/evm/iscmagic/ISCUtil.sol
@@ -10,10 +10,19 @@ import "./ISCTypes.sol";
  * @dev Functions of the ISC Magic Contract not directly related to the ISC sandbox
  */
 interface ISCUtil {
-    // Get an ISC contract's hname given its instance name
+    /**
+     * @notice Get an ISC contract's hname given its instance name
+     * @dev Converts a string instance name to its corresponding ISC hname.
+     * @param s The instance name of the ISC contract.
+     * @return The ISCHname corresponding to the given instance name.
+     */
     function hn(string memory s) external pure returns (ISCHname);
 
-    // Print something to the console (will only work when debugging contracts with Solo)
+    /**
+     * @notice Print something to the console (will only work when debugging contracts with Solo)
+     * @dev Prints the given string to the console for debugging purposes.
+     * @param s The string to print to the console.
+     */
     function print(string memory s) external pure;
 }