docs(world): add NatSpec to World utils (#1634)

Co-authored-by: alvarius <[email protected]>

packages/world/src/Utils.sol

@@ -5,17 +5,24 @@ import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";
 import { ResourceId, WorldResourceIdInstance } from "./WorldResourceId.sol";
 import { SystemRegistry } from "./codegen/tables/SystemRegistry.sol";
 
+/**
+ * @notice Various utilities
+ * @dev These utilities are not used by MUD itself, they are for developers using MUD.
+ */
 library Utils {
   using WorldResourceIdInstance for ResourceId;
 
   /**
-   * Get the namespace of this system.
-   * Must be used within the context of a system (either directly, or within libraries called by a system).
-   *
-   * Note unlike systemNamespace, getting systemName is impossible for root systems,
-   * because they're delegatecalled and the name isn't passed in calldata
+   * @notice Fetches the namespace of the current system.
+   * @dev This function determines the system's namespace based on its interaction with the store. If the system is a root system, it returns the root namespace (an empty string). Otherwise, it retrieves the namespace using the system's registry.
+   * This function must be used within the context of a system (either directly or within libraries called by a system).
+   * @return Returns a bytes14 representation of the system's namespace.
    */
-  function systemNamespace() internal view returns (bytes16) {
+  function systemNamespace() internal view returns (bytes14) {
+    /**
+     * Unlike systemNamespace, getting systemName is impossible for root systems,
+     * because they're delegatecalled and the name isn't passed in calldata
+     */
     if (StoreSwitch.getStoreAddress() == address(this)) {
       return "";
     } else {

packages/world/src/requireInterface.sol

@@ -5,7 +5,16 @@ import { IERC165 } from "./IERC165.sol";
 import { IWorldErrors } from "./IWorldErrors.sol";
 
 /**
- * Require the given contract to support the given interface by calling the ERC-165 supportsInterface function.
+ * @title Interface Validator
+ * @notice Utility function to validate interface support on a given contract using ERC-165.
+ * @dev This function uses the ERC-165 standard's `supportsInterface` to check if a given contract supports a specific interface.
+ */
+
+/**
+ * @notice Checks if a given contract at `contractAddress` supports the interface with ID `interfaceId`.
+ * @dev Uses the ERC-165 `supportsInterface` method. If the contract doesn't support the interface or doesn't implement ERC-165, the function will revert with a relevant error message.
+ * @param contractAddress The address of the contract to check.
+ * @param interfaceId The interface ID to verify.
  */
 function requireInterface(address contractAddress, bytes4 interfaceId) view {
   try IERC165(contractAddress).supportsInterface(interfaceId) returns (bool supported) {

packages/world/src/revertWithBytes.sol

@@ -2,7 +2,15 @@
 pragma solidity >=0.8.21;
 
 /**
- * Utility function to revert with raw bytes (eg. coming from a low level call or from a previously encoded error)
+ * @title Raw Bytes Reverter
+ * @notice Utility function to revert transactions with raw bytes.
+ * @dev This can be especially useful when reverting with a message obtained from a low-level call or a pre-encoded error.
+ */
+
+/**
+ * @notice Reverts the transaction using the provided raw bytes as the revert reason.
+ * @dev Uses assembly to perform the revert operation with the raw bytes.
+ * @param reason The raw bytes revert reason.
  */
 function revertWithBytes(bytes memory reason) pure {
   assembly {

packages/world/src/version.sol

@@ -1,4 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @dev World Version Constant
+ * Defines the version identifier for the World contract or module.
+ * This version identifier can be used for version checks, logging, and more.
+ */
+
 bytes32 constant WORLD_VERSION = "1.0.0-unaudited";