From feee27d453d4e49e4c9765ee0c191fbb3d1f20ad Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Fri, 29 Sep 2023 09:08:12 -0500 Subject: [PATCH] docs(world): add NatSpec to System contracts and interfaces (#1632) Co-authored-by: alvarius --- packages/world/src/ISystemHook.sol | 26 +++++++++++++++++++- packages/world/src/System.sol | 10 +++++--- packages/world/src/SystemCall.sol | 33 +++++++++++++++++++++----- packages/world/src/SystemHook.sol | 12 +++++++++- packages/world/src/systemHookTypes.sol | 17 +++++++++++++ 5 files changed, 87 insertions(+), 11 deletions(-) diff --git a/packages/world/src/ISystemHook.sol b/packages/world/src/ISystemHook.sol index c0e467745c..0855df34f1 100644 --- a/packages/world/src/ISystemHook.sol +++ b/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; } diff --git a/packages/world/src/System.sol b/packages/world/src/System.sol index ca3e2d16d3..d9a7117755 100644 --- a/packages/world/src/System.sol +++ b/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. } diff --git a/packages/world/src/SystemCall.sol b/packages/world/src/SystemCall.sol index d5cd06a788..3efc83a8a4 100644 --- a/packages/world/src/SystemCall.sol +++ b/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, diff --git a/packages/world/src/SystemHook.sol b/packages/world/src/SystemHook.sol index 59f0bd13dd..3e360438c7 100644 --- a/packages/world/src/SystemHook.sol +++ b/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; } diff --git a/packages/world/src/systemHookTypes.sol b/packages/world/src/systemHookTypes.sol index 999023f7eb..c0d7e819c9 100644 --- a/packages/world/src/systemHookTypes.sol +++ b/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;