From df118eba089875c71653c4959d74907c392572c6 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Fri, 23 Feb 2024 12:57:38 -0600 Subject: [PATCH] docs(*/reference): add links to code samples (#2305) --- docs/pages/store/reference/misc.mdx | 2 + docs/pages/store/reference/store-core.mdx | 9 ++- docs/pages/store/reference/store-hook.mdx | 3 +- docs/pages/store/reference/store.mdx | 4 + .../world/reference/delegation-external.mdx | 3 +- .../internal/init-module-implementation.mdx | 10 +++ .../world/reference/internal/systemcall.mdx | 2 + docs/pages/world/reference/resource-ids.mdx | 2 + docs/pages/world/reference/world-external.mdx | 16 ++++ docs/pages/world/reference/world.mdx | 2 + scripts/render-api-docs.ts | 78 +++++++++++++++++++ 11 files changed, 128 insertions(+), 3 deletions(-) diff --git a/docs/pages/store/reference/misc.mdx b/docs/pages/store/reference/misc.mdx index ae365f79b0..78e1f5d689 100644 --- a/docs/pages/store/reference/misc.mdx +++ b/docs/pages/store/reference/misc.mdx @@ -446,6 +446,8 @@ various constraints regarding the length and size of the fields._ #### encode +[Usage Sample](/world/namespaces-access-control#modifying-access-control) + Encodes the given field layout into a single bytes32. _Ensures various constraints on the length and size of the fields. diff --git a/docs/pages/store/reference/store-core.mdx b/docs/pages/store/reference/store-core.mdx index 0afc6d0ed0..4d9d0f1dd8 100644 --- a/docs/pages/store/reference/store-core.mdx +++ b/docs/pages/store/reference/store-core.mdx @@ -100,6 +100,8 @@ function getValueSchema(ResourceId tableId) internal view returns (Schema valueS #### registerTable +[Usage Sample](/store/tables#manually-register-a-table) + Register a new table with the given configuration. \*This method reverts if @@ -135,6 +137,8 @@ function registerTable( #### registerStoreHook +[Usage Sample](/store/store-hooks) + REGISTER HOOKS Register hooks to be called when a record or field is set or deleted. @@ -1485,7 +1489,8 @@ function getDynamicFieldSlice( ## StoreSwitch -[Git Source](https://github.com/latticexyz/mud/blob/main/packages/store/src/StoreSwitch.sol) +| [Usage Sample](/store/table-libraries#storeswitch) | [Git Source](https://github.com/latticexyz/mud/blob/main/packages/store/src/StoreSwitch.sol) | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | This library serves as an interface switch to interact with the store, either by directing calls to itself or to a designated external store. @@ -1538,6 +1543,8 @@ function getStoreAddress() internal view returns (address); #### setStoreAddress +[Usage Sample](/store/table-libraries#storeswitch) + Set the store address for subsequent operations. _If it stays uninitialized, StoreSwitch falls back to calling store methods on msg.sender._ diff --git a/docs/pages/store/reference/store-hook.mdx b/docs/pages/store/reference/store-hook.mdx index bce6a9c9ca..ab8b0f4583 100644 --- a/docs/pages/store/reference/store-hook.mdx +++ b/docs/pages/store/reference/store-hook.mdx @@ -2,7 +2,8 @@ ## IStoreHook -[Git Source](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreHook.sol) +| [Usage Sample](/store/store-hooks#store-hook-contract) | [Git Source](https://github.com/latticexyz/mud/blob/main/packages/store/src/IStoreHook.sol) | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | **Inherits:** [IERC165](/world/reference/internal/erc165-external#ierc165) diff --git a/docs/pages/store/reference/store.mdx b/docs/pages/store/reference/store.mdx index 20bcc354bf..df300ce8c7 100644 --- a/docs/pages/store/reference/store.mdx +++ b/docs/pages/store/reference/store.mdx @@ -490,6 +490,8 @@ making them less performance critical than the methods. #### registerTable +[Usage Sample](/store/tables#manually-register-a-table) + ```solidity function registerTable( ResourceId tableId, @@ -503,6 +505,8 @@ function registerTable( #### registerStoreHook +[Usage Sample](/store/store-hooks) + ```solidity function registerStoreHook(ResourceId tableId, IStoreHook hookAddress, uint8 enabledHooksBitmap) external; ``` diff --git a/docs/pages/world/reference/delegation-external.mdx b/docs/pages/world/reference/delegation-external.mdx index 3cc67a7b74..3f978c0aab 100644 --- a/docs/pages/world/reference/delegation-external.mdx +++ b/docs/pages/world/reference/delegation-external.mdx @@ -2,7 +2,8 @@ ## IDelegationControl -[Git Source](https://github.com/latticexyz/mud/blob/main/packages/world/src/IDelegationControl.sol) +| [Usage Sample](/world/account-delegation) | [Git Source](https://github.com/latticexyz/mud/blob/main/packages/world/src/IDelegationControl.sol) | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------- | **Inherits:** [IWorldContextConsumer](/world/reference/world-context-external#iworldcontextconsumer) diff --git a/docs/pages/world/reference/internal/init-module-implementation.mdx b/docs/pages/world/reference/internal/init-module-implementation.mdx index 6acb16654e..9f1642379d 100644 --- a/docs/pages/world/reference/internal/init-module-implementation.mdx +++ b/docs/pages/world/reference/internal/init-module-implementation.mdx @@ -142,6 +142,8 @@ function transferBalanceToNamespace( #### transferBalanceToAddress +[Usage Sample](/world/balance) + Transfer balance out of the World to a specific address. _Requires the caller to have access to the source namespace and ensures sufficient balance before transfer._ @@ -312,6 +314,8 @@ _This contract provides functions related to registering resources other than ta #### registerNamespace +[Usage Sample](/world/systems#registering-systems) + Registers a new namespace _Creates a new namespace resource with the given ID_ @@ -367,6 +371,8 @@ function unregisterSystemHook(ResourceId systemId, ISystemHook hookAddress) publ #### registerSystem +[Usage Sample](/world/systems#registering-systems) + Registers a system _Registers or upgrades a system at the given ID @@ -391,6 +397,8 @@ function registerSystem(ResourceId systemId, System system, bool publicAccess) p #### registerFunctionSelector +[Usage Sample](/world/function-selectors) + Registers a new World function selector _Creates a mapping between a World function and its associated system function_ @@ -417,6 +425,8 @@ function registerFunctionSelector( #### registerRootFunctionSelector +[Usage Sample](/world/function-selectors#root-function-selectors) + Registers a root World function selector _Creates a mapping for a root World function without namespace or name prefix_ diff --git a/docs/pages/world/reference/internal/systemcall.mdx b/docs/pages/world/reference/internal/systemcall.mdx index 94b9579e7c..2dafd8a466 100644 --- a/docs/pages/world/reference/internal/systemcall.mdx +++ b/docs/pages/world/reference/internal/systemcall.mdx @@ -11,6 +11,8 @@ It ensures the necessary access control checks, handles system hooks, and perfor #### call +[Usage Sample](/world/systems#using-call) + Calls a system identified by its Resource ID while ensuring necessary access controls. _This function does not revert if the system call fails. Instead, it returns a success flag._ diff --git a/docs/pages/world/reference/resource-ids.mdx b/docs/pages/world/reference/resource-ids.mdx index 4412bf98b7..5a6c7a5f0e 100644 --- a/docs/pages/world/reference/resource-ids.mdx +++ b/docs/pages/world/reference/resource-ids.mdx @@ -148,6 +148,8 @@ function encode(bytes2 typeId, bytes14 namespace, bytes16 name) internal pure re #### encodeNamespace +[Usage Sample](/world/systems#registering-systems) + Encode a namespace to resource ID. ```solidity diff --git a/docs/pages/world/reference/world-external.mdx b/docs/pages/world/reference/world-external.mdx index 3a587a5f10..5a3d336c12 100644 --- a/docs/pages/world/reference/world-external.mdx +++ b/docs/pages/world/reference/world-external.mdx @@ -30,6 +30,8 @@ function storeVersion() public pure returns (bytes32); #### registerTable +[Usage Sample](/store/tables#manually-register-a-table) + ```solidity function registerTable( ResourceId tableId, @@ -55,6 +57,8 @@ function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) externa #### grantAccess +[Usage Sample](/world/namespaces-access-control#modifying-access-control) + Grant access to the resource at the given resource ID. _Requires the caller to own the namespace._ @@ -72,6 +76,8 @@ function grantAccess(ResourceId resourceId, address grantee) public virtual only #### revokeAccess +[Usage Sample](/world/namespaces-access-control#modifying-access-control) + Revoke access from the resource at the given resource ID. _Requires the caller to own the namespace._ @@ -144,6 +150,8 @@ function transferBalanceToNamespace( #### transferBalanceToAddress +[Usage Sample](/world/balance) + Transfer balance out of the World to a specific address. _Requires the caller to have access to the source namespace and ensures sufficient balance before transfer._ @@ -230,6 +238,8 @@ function installModule(IModule module, bytes memory encodedArgs) public onlyDele #### registerNamespace +[Usage Sample](/world/systems#registering-systems) + Registers a new namespace _Creates a new namespace resource with the given ID_ @@ -285,6 +295,8 @@ function unregisterSystemHook(ResourceId systemId, ISystemHook hookAddress) publ #### registerSystem +[Usage Sample](/world/systems#registering-systems) + Registers a system _Registers or upgrades a system at the given ID @@ -335,6 +347,8 @@ function registerFunctionSelector( #### registerRootFunctionSelector +[Usage Sample](/world/function-selectors#root-function-selectors) + Registers a root World function selector _Creates a mapping for a root World function without namespace or name prefix_ @@ -521,6 +535,8 @@ _This interface defines the contract for executing calls on the World's systems. #### call +[Usage Sample](/world/systems#using-call) + 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)._ diff --git a/docs/pages/world/reference/world.mdx b/docs/pages/world/reference/world.mdx index 6ac0c4f3fd..f25400d6e3 100644 --- a/docs/pages/world/reference/world.mdx +++ b/docs/pages/world/reference/world.mdx @@ -316,6 +316,8 @@ function deleteRecord(ResourceId tableId, bytes32[] calldata keyTuple) public vi #### call +[Usage Sample](/world/systems#using-call) + SYSTEM CALLS Calls a system with a given system ID. diff --git a/scripts/render-api-docs.ts b/scripts/render-api-docs.ts index 8e3e70fe98..24cb0b6d3d 100644 --- a/scripts/render-api-docs.ts +++ b/scripts/render-api-docs.ts @@ -23,6 +23,11 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "store"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "registerTable", "/store/tables#manually-register-a-table"); + content = addSampleCodeFunction(content, "registerStoreHook", "/store/store-hooks"); + content = addSampleCodeFunction(content, "setStoreAddress", "/store/table-libraries#storeswitch"); + content = addSampleCodeContract(content, "StoreSwitch", "/store/table-libraries#storeswitch"); + return content.replaceAll("SET DATA\n", "").replaceAll("GET DATA\n", "").replaceAll("HELPER FUNCTIONS\n", ""); }, }, @@ -40,6 +45,9 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "store"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "registerTable", "/store/tables#manually-register-a-table"); + content = addSampleCodeFunction(content, "registerStoreHook", "/store/store-hooks"); + return content; }, }, @@ -53,6 +61,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "store"); content = fixInheritence(content); + content = addSampleCodeContract(content, "IStoreHook", "/store/store-hooks#store-hook-contract"); + return content; }, }, @@ -79,6 +89,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "store"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "encode", "/world/namespaces-access-control#modifying-access-control"); + return content .replace("## Constants", "## ResourceId.sol constants") .replace("## Constants", "## constants.sol") @@ -97,6 +109,7 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + return content; }, }, @@ -124,6 +137,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeContract(content, "IDelegationControl", "/world/account-delegation"); + return content; }, }, @@ -153,6 +168,7 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + return content; }, }, @@ -184,6 +200,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "call", "/world/systems#using-call"); + return content; }, }, @@ -202,6 +220,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "call", "/world/systems#using-call"); + return content .replace("StoreData", "[StoreData](/store/reference/store-core#storedata)") .replace(/#### _installRootModule((.|\n)*?)#### setRecord/m, "#### setRecord"); @@ -231,6 +251,27 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeFunction( + content, + "grantAccess", + "/world/namespaces-access-control#modifying-access-control" + ); + content = addSampleCodeFunction( + content, + "revokeAccess", + "/world/namespaces-access-control#modifying-access-control" + ); + content = addSampleCodeFunction(content, "registerTable", "/store/tables#manually-register-a-table"); + content = addSampleCodeFunction(content, "call", "/world/systems#using-call"); + content = addSampleCodeFunction(content, "registerNamespace", "/world/systems#registering-systems"); + content = addSampleCodeFunction(content, "registerSystem", "/world/systems#registering-systems"); + content = addSampleCodeFunction( + content, + "registerRootFunctionSelector", + "/world/function-selectors#root-function-selectors" + ); + content = addSampleCodeFunction(content, "transferBalanceToAddress", "/world/balance"); + return content .replace("IStore", "[IStore](/store/reference/store#istore)") .replaceAll("This is an autogenerated file; do not edit manually", "") @@ -274,6 +315,8 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "encodeNamespace", "/world/systems#registering-systems"); + return content .replace("Constants", "WorldResourceId.sol constants") .replace("Constants", "worldResourceTypes.sol constants"); @@ -321,6 +364,16 @@ const PUBLIC_APIS: PublicApis = { content = formatHeadings(content); content = fixGithubLinks(content, "world"); content = fixInheritence(content); + content = addSampleCodeFunction(content, "registerNamespace", "/world/systems#registering-systems"); + content = addSampleCodeFunction(content, "registerSystem", "/world/systems#registering-systems"); + content = addSampleCodeFunction(content, "registerFunctionSelector", "/world/function-selectors"); + content = addSampleCodeFunction( + content, + "registerRootFunctionSelector", + "/world/function-selectors#root-function-selectors" + ); + content = addSampleCodeFunction(content, "transferBalanceToAddress", "/world/balance"); + return content.replace("Constants", "constants.sol"); }, }, @@ -397,6 +450,31 @@ const inheritence = [ { contract: "IERC165-supportsInterface", link: "/world/reference/internal/erc165-external#supportsinterface" }, ]; +function addSampleCodeContract(content: string, contract: string, url: string): string { + const regexp = RegExp(`#+ ${contract}[\n ]+\\[Git Source\\]\\(.*\\)`); + return content.replace(regexp, (str) => + str + .replace( + ")", + `) | + | - | - |` + ) + .replace("[Git Source](", `| [Usage Sample](${url}) | [Git Source](`) + ); +} + +function addSampleCodeFunction(content: string, heading: string, url: string): string { + const regexp = RegExp(`#+ ${heading}\n`); + return content.replace(regexp, (str) => + str.replace( + "\n", + ` + [Usage Sample](${url}) + ` + ) + ); +} + /////////////////////////////////////////////////////////////////////////////////////////////////////// // SHOULDN'T HAVE TO TOUCH CODE BELOW THIS ///////////////////////////////////////////////////////////////////////////////////////////////////////