docs(world): add NatSpec to System contracts and interfaces (#1632)

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

packages/world/src/ISystemHook.sol

@@ -4,13 +4,37 @@ pragma solidity >=0.8.21;
 import { IERC165, ERC165_INTERFACE_ID } from "./IERC165.sol";
 import { ResourceId } from "./WorldResourceId.sol";
 
-// ERC-165 Interface ID (see https://eips.ethereum.org/EIPS/eip-165)
+/**
+ * @dev Calculation for ERC-165 interface ID for the ISystemHook functions.
+ * Combines the selector for each function with the ERC165_INTERFACE_ID.
+ * See: https://eips.ethereum.org/EIPS/eip-165
+ */
 bytes4 constant SYSTEM_HOOK_INTERFACE_ID = ISystemHook.onBeforeCallSystem.selector ^
   ISystemHook.onAfterCallSystem.selector ^
   ERC165_INTERFACE_ID;
 
+/**
+ * @title ISystemHook
+ * @dev Interface defining system hooks for external functionality.
+ * Provides pre and post hooks that can be triggered before and after a system call respectively.
+ * This interface adheres to the ERC-165 standard for determining interface support.
+ */
 interface ISystemHook is IERC165 {
+  /**
+   * @notice Executes before a system call.
+   * @dev Provides the ability to add custom logic or checks before a system is invoked.
+   * @param msgSender The original sender of the system call.
+   * @param systemId The identifier for the system being called.
+   * @param callData Data being sent as part of the system call.
+   */
   function onBeforeCallSystem(address msgSender, ResourceId systemId, bytes memory callData) external;
 
+  /**
+   * @notice Executes after a system call.
+   * @dev Provides the ability to add custom logic or checks after a system call completes.
+   * @param msgSender The original sender of the system call.
+   * @param systemId The identifier for the system that was called.
+   * @param callData Data that was sent as part of the system call.
+   */
   function onAfterCallSystem(address msgSender, ResourceId systemId, bytes memory callData) external;
 }

packages/world/src/System.sol

@@ -3,8 +3,12 @@ pragma solidity >=0.8.21;
 
 import { WorldContextConsumer } from "./WorldContext.sol";
 
-// For now System is just an alias for `WorldContextConsumer`,
-// but we might add more default functionality in the future.
-contract System is WorldContextConsumer {
+/**
+ * @title System
+ * @dev The System contract currently acts as an alias for `WorldContextConsumer`.
+ * This structure is chosen for potential extensions in the future, where default functionality might be added to the System.
+ */
 
+contract System is WorldContextConsumer {
+  // Currently, no additional functionality is added. Future enhancements can be introduced here.
 }

packages/world/src/SystemCall.sol

@@ -19,12 +19,23 @@ import { Systems } from "./codegen/tables/Systems.sol";
 import { SystemHooks } from "./codegen/tables/SystemHooks.sol";
 import { Balances } from "./codegen/tables/Balances.sol";
 
+/**
+ * @title SystemCall
+ * @dev The SystemCall library provides functions for interacting with systems using their unique Resource IDs.
+ * It ensures the necessary access control checks, handles system hooks, and performs system calls.
+ */
 library SystemCall {
   using WorldResourceIdInstance for ResourceId;
 
   /**
-   * Calls a system via its ID and perform access control checks.
-   * Does not revert if the call fails, but returns a `success` flag along with the returndata.
+   * @notice Calls a system identified by its Resource ID while ensuring necessary access controls.
+   * @dev This function does not revert if the system call fails. Instead, it returns a success flag.
+   * @param caller The address initiating the system call.
+   * @param value The amount of Ether to be sent with the call.
+   * @param systemId The unique Resource ID of the system being called.
+   * @param callData The calldata to be executed in the system.
+   * @return success A flag indicating whether the system call was successful.
+   * @return data The return data from the system call.
    */
   function call(
     address caller,
@@ -65,8 +76,14 @@ library SystemCall {
   }
 
   /**
-   * Calls a system via its ID, perform access control checks and trigger hooks registered for the system.
-   * Does not revert if the call fails, but returns a `success` flag along with the returndata.
+   * @notice Calls a system identified by its Resource ID, ensuring access controls, and triggers associated system hooks.
+   * @dev This function does not revert if the system call fails. Instead, it returns a success flag.
+   * @param caller The address initiating the system call.
+   * @param systemId The unique Resource ID of the system being called.
+   * @param callData The calldata to be executed in the system.
+   * @param value The amount of Ether to be sent with the call.
+   * @return success A flag indicating whether the system call was successful.
+   * @return data The return data from the system call.
    */
   function callWithHooks(
     address caller,
@@ -98,8 +115,12 @@ library SystemCall {
   }
 
   /**
-   * Calls a system via its ID, perform access control checks and trigger hooks registered for the system.
-   * Reverts if the call fails.
+   * @notice Calls a system identified by its Resource ID, ensures access controls, triggers associated system hooks, and reverts on failure.
+   * @param caller The address initiating the system call.
+   * @param systemId The unique Resource ID of the system being called.
+   * @param callData The calldata to be executed in the system.
+   * @param value The amount of Ether to be sent with the call.
+   * @return data The return data from the system call.
    */
   function callWithHooksOrRevert(
     address caller,

packages/world/src/SystemHook.sol

@@ -4,8 +4,18 @@ pragma solidity >=0.8.21;
 import { ISystemHook, SYSTEM_HOOK_INTERFACE_ID } from "./ISystemHook.sol";
 import { ERC165_INTERFACE_ID } from "./IERC165.sol";
 
+/**
+ * @title SystemHook
+ * @dev The abstract SystemHook contract implements the ERC-165 supportsInterface function for ISystemHook.
+ * System hooks are used for executing additional logic before or after certain system actions.
+ */
 abstract contract SystemHook is ISystemHook {
-  // ERC-165 supportsInterface (see https://eips.ethereum.org/EIPS/eip-165)
+  /**
+   * @notice Checks if the contract implements a given interface.
+   * @dev Overridden from IERC165 to include the system hook interface.
+   * @param interfaceId The bytes4 interface identifier, as specified in ERC-165.
+   * @return true if the contract implements `interfaceId`, false otherwise.
+   */
   function supportsInterface(bytes4 interfaceId) public view virtual returns (bool) {
     return interfaceId == SYSTEM_HOOK_INTERFACE_ID || interfaceId == ERC165_INTERFACE_ID;
   }

packages/world/src/systemHookTypes.sol

@@ -1,7 +1,24 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title System Hook Types
+ * @dev This file provides constants for defining the different types of system hooks.
+ * System hooks can be used to execute additional logic before or after system actions.
+ */
+
+/**
+ * @dev Constant representing a hook that is triggered before a system call.
+ */
 uint8 constant BEFORE_CALL_SYSTEM = 1 << 0;
+
+/**
+ * @dev Constant representing a hook that is triggered after a system call.
+ */
 uint8 constant AFTER_CALL_SYSTEM = 1 << 1;
 
+/**
+ * @dev Constant representing all types of system hooks.
+ * It's a bitmap with flags from all system hook types enabled.
+ */
 uint8 constant ALL = BEFORE_CALL_SYSTEM | AFTER_CALL_SYSTEM;