From fd10cff6afc93f1c3e2fb657340edebeb51a4ec2 Mon Sep 17 00:00:00 2001
From: Ori Pomerantz <qbzzt1@gmail.com>
Date: Fri, 29 Sep 2023 08:40:48 -0500
Subject: [PATCH] docs(world): add NatSpec to IModule, Module (#1631)

Co-authored-by: alvarius <alvarius@lattice.xyz>
---
 packages/world/src/IModule.sol | 32 ++++++++++++++++++++++++--------
 packages/world/src/Module.sol  | 11 ++++++++++-
 2 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/packages/world/src/IModule.sol b/packages/world/src/IModule.sol
index e5c474634a..898cb59d76 100644
--- a/packages/world/src/IModule.sol
+++ b/packages/world/src/IModule.sol
@@ -3,32 +3,48 @@ 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 Calculation for ERC-165 interface ID for the IModule functions.
+ * Combines the selector for each function with the ERC165_INTERFACE_ID.
+ * See: https://eips.ethereum.org/EIPS/eip-165
+ */
 bytes4 constant MODULE_INTERFACE_ID = IModule.getName.selector ^
   IModule.installRoot.selector ^
   IModule.install.selector ^
   ERC165_INTERFACE_ID;
 
+/**
+ * @title IModule
+ * @dev Interface for the Module system.
+ * A module can be installed within the context of a world, either as a root or non-root module.
+ * This interface adheres to the ERC-165 standard for determining interface support.
+ */
 interface IModule is IERC165 {
+  /// @dev Errors to represent non-support of specific installation types.
   error Module_RootInstallNotSupported();
   error Module_NonRootInstallNotSupported();
 
   /**
-   * Return the module name as a bytes16.
+   * @notice Return the name of the module.
+   * @dev Provides a way to identify the module by a unique name.
+   * @return name The name of the module as a bytes16.
    */
   function getName() external view returns (bytes16 name);
 
   /**
-   * This function is called by the World as part of `installRootModule`.
-   * The module expects to be called via the World contract, and therefore installs itself on the `msg.sender`.
+   * @notice Installs the module as a root module.
+   * @dev This function is invoked by the World contract during `installRootModule` process.
+   * The module expects to be called via the World contract and thus installs itself on the `msg.sender`.
+   * @param args Arguments that may be needed during the installation process.
    */
   function installRoot(bytes memory args) external;
 
   /**
-   * This function is called by the World as part of `installModule`.
-   * The module expects to be called via the World contract, and therefore installs itself on the `msg.sender`.
-   * This function is separate from `installRoot` because the logic might be different (eg. accepting namespace parameters,
-   * or using `callFrom`)
+   * @notice Installs the module.
+   * @dev This function is invoked by the World contract during `installModule` process.
+   * The module expects to be called via the World contract and thus installs itself on the `msg.sender`.
+   * Logic might differ from `installRoot`, for example, this might accept namespace parameters.
+   * @param args Arguments that may be needed during the installation process.
    */
   function install(bytes memory args) external;
 }
diff --git a/packages/world/src/Module.sol b/packages/world/src/Module.sol
index 0914a155bd..6bf4c64921 100644
--- a/packages/world/src/Module.sol
+++ b/packages/world/src/Module.sol
@@ -5,8 +5,17 @@ import { WorldContextConsumer } from "./WorldContext.sol";
 import { IModule, MODULE_INTERFACE_ID } from "./IModule.sol";
 import { IERC165, ERC165_INTERFACE_ID } from "./IERC165.sol";
 
+/**
+ * @title Module
+ * @dev Abstract contract that implements the ERC-165 supportsInterface function for IModule.
+ */
 abstract contract Module is IModule, WorldContextConsumer {
-  // ERC-165 supportsInterface (see https://eips.ethereum.org/EIPS/eip-165)
+  /**
+   * @notice Checks if the given interfaceId is supported by this contract.
+   * @dev Overrides the functionality from IERC165 and WorldContextConsumer to check for supported interfaces.
+   * @param interfaceId The bytes4 identifier for the interface.
+   * @return true if the interface is supported, false otherwise.
+   */
   function supportsInterface(
     bytes4 interfaceId
   ) public pure virtual override(IERC165, WorldContextConsumer) returns (bool) {