docs(world): add NatSpec to CoreModule (#1664)

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

packages/world/src/modules/core/CoreModule.sol

@@ -35,33 +35,47 @@ import { StoreRegistrationSystem } from "./implementations/StoreRegistrationSyst
 import { WorldRegistrationSystem } from "./implementations/WorldRegistrationSystem.sol";
 
 /**
- * The CoreModule registers internal World tables, the CoreSystem, and its function selectors.
-
- * Note:
- * This module only supports `installRoot` (via `World.registerRootSystem`),
- * because it needs to install root tables, systems and function selectors.
+ * @title Core Module
+ * @notice Registers internal World tables, the CoreSystem, and its function selectors.
+ * @dev This module only supports `installRoot` because it installs root tables, systems and function selectors.
  */
+
 contract CoreModule is Module {
-  // Since the CoreSystem only exists once per World and writes to
-  // known tables, we can deploy it once and register it in multiple Worlds.
+  /**
+   * @dev Since the CoreSystem only exists once per World and writes to
+   * known tables, we can deploy it once and register it in multiple Worlds.
+   */
   address immutable coreSystem = address(new CoreSystem());
 
+  /**
+   * @notice Get the name of the module.
+   * @return Module name as bytes16.
+   */
   function getName() public pure returns (bytes16) {
     return CORE_MODULE_NAME;
   }
 
+  /**
+   * @notice Root installation of the module.
+   * @dev Registers core tables, systems, and function selectors in the World.
+   */
   function installRoot(bytes memory) public override {
     _registerCoreTables();
     _registerCoreSystem();
     _registerFunctionSelectors();
   }
 
+  /**
+   * @notice Non-root installation of the module.
+   * @dev Installation is only supported at root level, so this function will always revert.
+   */
   function install(bytes memory) public pure {
     revert Module_NonRootInstallNotSupported();
   }
 
   /**
-   * Register core tables in the World
+   * @notice Register core tables in the World.
+   * @dev This internal function registers various tables and sets initial permissions.
    */
   function _registerCoreTables() internal {
     StoreCore.registerCoreTables();
@@ -86,10 +100,10 @@ contract CoreModule is Module {
   }
 
   /**
-   * Register the CoreSystem in the World
+   * @notice Register the CoreSystem in the World.
+   * @dev Uses the CoreSystem's `registerSystem` implementation to register itself on the World.
    */
   function _registerCoreSystem() internal {
-    // Use the CoreSystem's `registerSystem` implementation to register itself on the World.
     WorldContextProvider.delegatecallWithContextOrRevert({
       msgSender: _msgSender(),
       msgValue: 0,
@@ -99,7 +113,8 @@ contract CoreModule is Module {
   }
 
   /**
-   * Register function selectors for all CoreSystem functions in the World
+   * @notice Register function selectors for all CoreSystem functions in the World.
+   * @dev Iterates through known function signatures and registers them.
    */
   function _registerFunctionSelectors() internal {
     string[19] memory functionSignatures = [

packages/world/src/modules/core/CoreSystem.sol

@@ -11,8 +11,9 @@ import { StoreRegistrationSystem } from "./implementations/StoreRegistrationSyst
 import { WorldRegistrationSystem } from "./implementations/WorldRegistrationSystem.sol";
 
 /**
- * The CoreSystem includes all World functionality that is externalized
- * from the World contract to keep the World contract's bytecode as lean as possible.
+ * @title Core System for World
+ * @notice This system aggregates all World functionalities externalized from the World contract, aiming to keep the World contract's bytecode lean.
+ * @dev Aggregates multiple system implementations for the World.
  */
 contract CoreSystem is
   IWorldErrors,
@@ -23,5 +24,4 @@ contract CoreSystem is
   StoreRegistrationSystem,
   WorldRegistrationSystem
 {
-
 }

packages/world/src/modules/core/constants.sol

@@ -6,8 +6,16 @@ import { ResourceId } from "@latticexyz/store/src/ResourceId.sol";
 import { ROOT_NAMESPACE } from "../../constants.sol";
 import { RESOURCE_SYSTEM } from "../../worldResourceTypes.sol";
 
+/**
+ * @dev Name of the core module.
+ * @dev Represented as a bytes16 constant.
+ */
 bytes16 constant CORE_MODULE_NAME = bytes16("core");
 
+/**
+ * @dev Resource ID for the core system.
+ * @dev This ID is derived from the RESOURCE_SYSTEM type, the ROOT_NAMESPACE, and the CORE_MODULE_NAME.
+ */
 ResourceId constant CORE_SYSTEM_ID = ResourceId.wrap(
   bytes32(abi.encodePacked(RESOURCE_SYSTEM, ROOT_NAMESPACE, CORE_MODULE_NAME))
 );

packages/world/src/modules/core/implementations/AccessManagementSystem.sol

@@ -10,12 +10,15 @@ import { InstalledModules } from "../../../codegen/tables/InstalledModules.sol";
 import { NamespaceOwner } from "../../../codegen/tables/NamespaceOwner.sol";
 
 /**
- * Granting and revoking access from/to resources.
+ * @title Access Management System
+ * @dev This contract manages the granting and revoking of access from/to resources.
  */
 contract AccessManagementSystem is System {
   /**
-   * Grant access to the resource at the given resource ID.
-   * Requires the caller to own the namespace.
+   * @notice Grant access to the resource at the given resource ID.
+   * @dev Requires the caller to own the namespace.
+   * @param resourceId The ID of the resource to grant access to.
+   * @param grantee The address to which access should be granted.
    */
   function grantAccess(ResourceId resourceId, address grantee) public virtual {
     // Require the caller to own the namespace
@@ -26,8 +29,10 @@ contract AccessManagementSystem is System {
   }
 
   /**
-   * Revoke access from the resource at the given resource ID.
-   * Requires the caller to own the namespace.
+   * @notice Revoke access from the resource at the given resource ID.
+   * @dev Requires the caller to own the namespace.
+   * @param resourceId The ID of the resource to revoke access from.
+   * @param grantee The address from which access should be revoked.
    */
   function revokeAccess(ResourceId resourceId, address grantee) public virtual {
     // Require the caller to own the namespace
@@ -38,9 +43,10 @@ contract AccessManagementSystem is System {
   }
 
   /**
-   * Transfer ownership of the given namespace to newOwner.
-   * Revoke ResourceAccess for previous owner and grant to newOwner.
-   * Requires the caller to own the namespace.
+   * @notice Transfer ownership of the given namespace to newOwner and manages the access.
+   * @dev Requires the caller to own the namespace. Revoke ResourceAccess for previous owner and grant to newOwner.
+   * @param namespaceId The ID of the namespace to transfer ownership.
+   * @param newOwner The address to which ownership should be transferred.
    */
   function transferOwnership(ResourceId namespaceId, address newOwner) public virtual {
     // Require the caller to own the namespace

packages/world/src/modules/core/implementations/BalanceTransferSystem.sol

@@ -12,12 +12,20 @@ import { IWorldErrors } from "../../../IWorldErrors.sol";
 
 import { Balances } from "../../../codegen/tables/Balances.sol";
 
+/**
+ * @title Balance Transfer System
+ * @dev A system contract that facilitates balance transfers in the World and outside of the World.
+ */
 contract BalanceTransferSystem is System, IWorldErrors {
   using ResourceIdInstance for ResourceId;
   using WorldResourceIdInstance for ResourceId;
 
   /**
-   * Transfer balance to another namespace in the World
+   * @notice Transfer balance to another namespace in the World.
+   * @dev Requires the caller to have access to the source namespace and ensures the destination namespace type is valid.
+   * @param fromNamespaceId The source namespace from which the balance will be deducted.
+   * @param toNamespaceId The target namespace where the balance will be added.
+   * @param amount The amount to transfer.
    */
   function transferBalanceToNamespace(
     ResourceId fromNamespaceId,
@@ -44,7 +52,11 @@ contract BalanceTransferSystem is System, IWorldErrors {
   }
 
   /**
-   * Transfer balance out of the World
+   * @notice Transfer balance out of the World to a specific address.
+   * @dev Requires the caller to have access to the source namespace and ensures sufficient balance before transfer.
+   * @param fromNamespaceId The source namespace from which the balance will be deducted.
+   * @param toAddress The target address where the balance will be sent.
+   * @param amount The amount to transfer.
    */
   function transferBalanceToAddress(ResourceId fromNamespaceId, address toAddress, uint256 amount) public virtual {
     // Require caller to have access to the namespace

packages/world/src/modules/core/implementations/BatchCallSystem.sol

@@ -7,9 +7,16 @@ import { revertWithBytes } from "../../../revertWithBytes.sol";
 
 import { SystemCallData, SystemCallFromData } from "../types.sol";
 
+/**
+ * @title Batch Call System
+ * @dev A system contract that facilitates batching of calls to various systems in a single transaction.
+ */
 contract BatchCallSystem is System {
   /**
-   * Batch calls to multiple systems into a single transaction, return the array of return data.
+   * @notice Make batch calls to multiple systems into a single transaction.
+   * @dev Iterates through an array of system calls, executes them, and returns an array of return data.
+   * @param systemCalls An array of SystemCallData that contains systemId and callData for each call.
+   * @return returnDatas An array of bytes containing the return data for each system call.
    */
   function batchCall(SystemCallData[] calldata systemCalls) public returns (bytes[] memory returnDatas) {
     IBaseWorld world = IBaseWorld(_world());
@@ -26,7 +33,10 @@ contract BatchCallSystem is System {
   }
 
   /**
-   * Batch calls to multiple systems into a single transaction, return the array of return data.
+   * @notice Make batch calls from specific addresses to multiple systems in a single transaction.
+   * @dev Iterates through an array of system calls with specified 'from' addresses, executes them, and returns an array of return data.
+   * @param systemCalls An array of SystemCallFromData that contains from, systemId, and callData for each call.
+   * @return returnDatas An array of bytes containing the return data for each system call.
    */
   function batchCallFrom(SystemCallFromData[] calldata systemCalls) public returns (bytes[] memory returnDatas) {
     IBaseWorld world = IBaseWorld(_world());

packages/world/src/modules/core/implementations/ModuleInstallationSystem.sol

@@ -10,11 +10,16 @@ import { InstalledModules } from "../../../codegen/tables/InstalledModules.sol";
 import { requireInterface } from "../../../requireInterface.sol";
 
 /**
- * Installation of (non-root) modules in the World.
+ * @title Module Installation System
+ * @dev A system contract to handle the installation of (non-root) modules in the World.
  */
 contract ModuleInstallationSystem is System {
   /**
-   * Install the given module at the given namespace in the World.
+   * @notice Installs a module into the World under a specified namespace.
+   * @dev Validates the given module against the IModule interface and delegates the installation process.
+   * The module is then registered in the InstalledModules table.
+   * @param module The module to be installed.
+   * @param args Arguments for the module installation.
    */
   function installModule(IModule module, bytes memory args) public {
     // Require the provided address to implement the IModule interface

packages/world/src/modules/core/implementations/StoreRegistrationSystem.sol

@@ -29,13 +29,22 @@ import { CORE_SYSTEM_ID } from "../constants.sol";
 import { WorldRegistrationSystem } from "./WorldRegistrationSystem.sol";
 
 /**
- * Functions related to registering table resources in the World.
+ * @title Store Registration System
+ * @dev This contract provides functionality for the registration of store-related resources within the World framework.
  */
 contract StoreRegistrationSystem is System, IWorldErrors {
   using WorldResourceIdInstance for ResourceId;
 
   /**
-   * Register a table with the given config
+   * @notice Register a table within the World framework.
+   * @dev Registers a table with the specified configuration. If the namespace for the table does not exist, it's created.
+   * Existing namespaces require the caller to be the owner for table registration.
+   * @param tableId The resource ID of the table.
+   * @param fieldLayout The field layout structure for the table.
+   * @param keySchema The schema for the keys of the table.
+   * @param valueSchema The schema for the values within the table.
+   * @param keyNames The names associated with the keys in the table.
+   * @param fieldNames The names of the fields in the table.
    */
   function registerTable(
     ResourceId tableId,
@@ -68,9 +77,14 @@ contract StoreRegistrationSystem is System, IWorldErrors {
   }
 
   /**
-   * Register a hook for the given tableId.
-   * Requires the caller to own the namespace.
+   * @notice Register a storage hook for a specified table.
+   * @dev The caller must be the owner of the namespace to which the table belongs.
+   * The hook must conform to the IStoreHook interface.
+   * @param tableId The resource ID of the table for which the hook is being registered.
+   * @param hookAddress The address of the storage hook contract.
+   * @param enabledHooksBitmap A bitmap indicating which hooks are enabled.
    */
+
   function registerStoreHook(ResourceId tableId, IStoreHook hookAddress, uint8 enabledHooksBitmap) public virtual {
     // Require the hook to implement the store hook interface
     requireInterface(address(hookAddress), STORE_HOOK_INTERFACE_ID);
@@ -83,8 +97,10 @@ contract StoreRegistrationSystem is System, IWorldErrors {
   }
 
   /**
-   * Unregister a hook for the given tableId.
-   * Requires the caller to own the namespace.
+   * @notice Unregister a previously registered storage hook for a specified table.
+   * @dev The caller must be the owner of the namespace to which the table belongs.
+   * @param tableId The resource ID of the table from which the hook is being unregistered.
+   * @param hookAddress The address of the storage hook contract.
    */
   function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) public virtual {
     // Require caller to own the namespace