docs(world): add NatSpec to core source files (#1633)

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

packages/world/src/IWorldContextConsumer.sol

@@ -3,16 +3,43 @@ pragma solidity >=0.8.21;
 
 import { IERC165, ERC165_INTERFACE_ID } from "./IERC165.sol";
 
-// ERC-165 Interface ID (see https://eips.ethereum.org/EIPS/eip-165)
+/**
+ * @dev World Context Consumer Interface
+ * This interface defines the functions a contract needs to consume the world context.
+ * It includes helper functions to retrieve the message sender, value, and world address.
+ * Additionally, it integrates with the ERC-165 standard for interface detection.
+ */
+
 bytes4 constant WORLD_CONTEXT_CONSUMER_INTERFACE_ID = IWorldContextConsumer._msgSender.selector ^
   IWorldContextConsumer._msgValue.selector ^
   IWorldContextConsumer._world.selector ^
   ERC165_INTERFACE_ID;
 
+/**
+ * @title WorldContextConsumer - Extracting trusted context values from appended calldata.
+ * @notice This contract is designed to extract trusted context values (like msg.sender and msg.value)
+ * from the appended calldata. It provides mechanisms similar to EIP-2771 (https://eips.ethereum.org/EIPS/eip-2771),
+ * but allowing any contract to be the trusted forwarder.
+ * @dev This contract should only be used for contracts without their own storage, like Systems.
+ */
 interface IWorldContextConsumer is IERC165 {
+  /**
+   * @notice Extract the `msg.sender` from the context appended to the calldata.
+   * @return The address of the `msg.sender` that called the World contract
+   * before the World routed the call to the WorldContextConsumer contract.
+   */
   function _msgSender() external view returns (address);
 
+  /**
+   * @notice Extract the `msg.value` from the context appended to the calldata.
+   * @return The `msg.value` in the call to the World contract before the World routed the
+   * call to the WorldContextConsumer contract.
+   */
   function _msgValue() external view returns (uint256);
 
+  /**
+   * @notice Get the address of the World contract that routed the call to this WorldContextConsumer.
+   * @return The address of the World contract that routed the call to this WorldContextConsumer.
+   */
   function _world() external view returns (address);
 }

packages/world/src/IWorldErrors.sol

@@ -3,19 +3,101 @@ pragma solidity >=0.8.21;
 
 import { ResourceId } from "@latticexyz/store/src/ResourceId.sol";
 
+/**
+ * @title World Errors Interface
+ * @dev This interface contains custom error types for the World contract. These errors provide
+ * more informative messages for certain operations within the World contract.
+ */
 interface IWorldErrors {
+  /**
+   * @notice Raised when trying to initialize an already initialized World.
+   */
   error World_AlreadyInitialized();
+
+  /**
+   * @notice Raised when trying to register a resource that already exists.
+   * @param resourceId The ID of the resource.
+   * @param resourceIdString The string representation of the resource ID.
+   */
   error World_ResourceAlreadyExists(ResourceId resourceId, string resourceIdString);
+
+  /**
+   * @notice Raised when the specified resource is not found.
+   * @param resourceId The ID of the resource.
+   * @param resourceIdString The string representation of the resource ID.
+   */
   error World_ResourceNotFound(ResourceId resourceId, string resourceIdString);
+
+  /**
+   * @notice Raised when a user tries to access a resource they don't have permission for.
+   * @param resource The resource's identifier.
+   * @param caller The address of the user trying to access the resource.
+   */
   error World_AccessDenied(string resource, address caller);
+
+  /**
+   * @notice Raised when an invalid resource ID is provided.
+   * @param resourceId The ID of the resource.
+   * @param resourceIdString The string representation of the resource ID.
+   */
   error World_InvalidResourceId(ResourceId resourceId, string resourceIdString);
+
+  /**
+   * @notice Raised when trying to register a system that already exists.
+   * @param system The address of the system.
+   */
   error World_SystemAlreadyExists(address system);
+
+  /**
+   * @notice Raised when trying to register a function selector that already exists.
+   * @param functionSelector The function selector in question.
+   */
   error World_FunctionSelectorAlreadyExists(bytes4 functionSelector);
+
+  /**
+   * @notice Raised when the specified function selector is not found.
+   * @param functionSelector The function selector in question.
+   */
   error World_FunctionSelectorNotFound(bytes4 functionSelector);
+
+  /**
+   * @notice Raised when the specified delegation is not found.
+   * @param delegator The address of the delegator.
+   * @param delegatee The address of the delegatee.
+   */
   error World_DelegationNotFound(address delegator, address delegatee);
+
+  /**
+   * @notice Raised when trying to create an unlimited delegation in a context where it is not allowed,
+   * e.g. when registering a namespace fallback delegation.
+   */
   error World_UnlimitedDelegationNotAllowed();
+
+  /**
+   * @notice Raised when there's an insufficient balance for a particular operation.
+   * @param balance The current balance.
+   * @param amount The amount needed.
+   */
   error World_InsufficientBalance(uint256 balance, uint256 amount);
+
+  /**
+   * @notice Raised when the specified interface is not supported by the contract.
+   * @param contractAddress The address of the contract in question.
+   * @param interfaceId The ID of the interface.
+   */
   error World_InterfaceNotSupported(address contractAddress, bytes4 interfaceId);
+
+  /**
+   * @notice Raised when an invalid resource type is provided.
+   * @param expected The expected resource type.
+   * @param resourceId The ID of the resource.
+   * @param resourceIdString The string representation of the resource ID.
+   */
   error World_InvalidResourceType(bytes2 expected, ResourceId resourceId, string resourceIdString);
+
+  /**
+   * @notice Raised when the World is calling itself via an external call.
+   * @param functionSelector The function selector of the disallowed callback.
+   */
   error World_CallbackNotAllowed(bytes4 functionSelector);
 }

packages/world/src/IWorldFactory.sol

@@ -1,10 +1,27 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.8.21;
 
+/**
+ * @title World Factory Interface
+ * @dev This interface defines the contract responsible for deploying and keeping track
+ * of World contract instances.
+ */
 interface IWorldFactory {
+  /**
+   * @dev Emitted when a new World contract is deployed.
+   * @param newContract The address of the newly deployed World contract.
+   */
   event WorldDeployed(address indexed newContract);
 
+  /**
+   * @notice Returns the total count of deployed World contracts.
+   * @return The total number of World contracts deployed by this factory.
+   */
   function worldCount() external view returns (uint256);
 
+  /**
+   * @notice Deploys a new World contract.
+   * @dev The deployment of the World contract will result in the `WorldDeployed` event being emitted.
+   */
   function deployWorld() external;
 }

packages/world/src/IWorldKernel.sol

@@ -5,25 +5,43 @@ import { IWorldErrors } from "./IWorldErrors.sol";
 import { IModule } from "./IModule.sol";
 import { ResourceId } from "./WorldResourceId.sol";
 
+/**
+ * @title World Module Installation Interface
+ * @dev This interface defines the contract responsible for managing root modules installation.
+ */
 interface IWorldModuleInstallation {
   /**
-   * Install the given root module in the World.
-   * Requires the caller to own the root namespace.
-   * The module is delegatecalled and installed in the root namespace.
+   * @notice Install the given root module in the World.
+   * @dev Requires the caller to own the root namespace. The module is delegatecalled and installed in the root namespace.
+   * @param module The module to be installed.
+   * @param args The arguments provided for the module installation.
    */
   function installRootModule(IModule module, bytes memory args) external;
 }
 
+/**
+ * @title World Call Interface
+ * @dev This interface defines the contract for executing calls on the World's systems.
+ */
 interface IWorldCall {
   /**
-   * Call the system at the given system ID.
-   * If the system is not public, the caller must have access to the namespace or name (encoded in the system ID).
+   * @notice Call the system at the given system ID.
+   * @dev If the system is not public, the caller must have access to the namespace or name (encoded in the system ID).
+   * @param systemId The ID of the system to be called.
+   * @param callData The data to pass with the call,
+   * function selector (4 bytes) followed by the ABI encoded parameters.
+   * @return The abi encoded return data from the called system.
    */
   function call(ResourceId systemId, bytes memory callData) external payable returns (bytes memory);
 
   /**
-   * Call the system at the given system ID on behalf of the given delegator.
-   * If the system is not public, the delegator must have access to the namespace or name (encoded in the system ID).
+   * @notice Call the system at the given system ID on behalf of the given delegator.
+   * @dev If the system is not public, the delegator must have access to the namespace or name (encoded in the system ID).
+   * @param delegator The address on whose behalf the call is made.
+   * @param systemId The ID of the system to be called.
+   * @param callData The data to pass with the call,
+   * function selector (4 bytes) followed by the ABI encoded parameters.
+   * @return The abi encoded return data from the called system.
    */
   function callFrom(
     address delegator,
@@ -33,27 +51,34 @@ interface IWorldCall {
 }
 
 /**
- * The IWorldKernel interface includes all methods that are part of the World contract's
- * internal bytecode.
- *
- * Consumers should use the `IBaseWorld` interface instead, which includes dynamically
+ * @title World Kernel Interface
+ * @notice The IWorldKernel interface includes all methods that are part of the World contract's
+ * internal bytecode. Consumers should use the `IBaseWorld` interface instead, which includes dynamically
  * registered functions selectors from the `CoreModule`.
  */
 interface IWorldKernel is IWorldModuleInstallation, IWorldCall, IWorldErrors {
+  /**
+   * @dev Emitted upon successful World initialization.
+   * @param worldVersion The version of the World being initialized.
+   */
   event HelloWorld(bytes32 indexed worldVersion);
 
   /**
-   * The version of the World.
+   * @notice Retrieve the version of the World.
+   * @return The version identifier of the World.
    */
   function worldVersion() external view returns (bytes32);
 
   /**
-   * The immutable original deployer of the World.
+   * @notice Retrieve the immutable original deployer of the World.
+   * @return The address of the World's creator.
    */
   function creator() external view returns (address);
 
   /**
-   * Allows the creator of the World to initialize the World once.
+   * @notice Initializes the World.
+   * @dev Can only be called once by the creator.
+   * @param coreModule The CoreModule to be installed during initialization.
    */
   function initialize(IModule coreModule) external;
 }