Skip to content

Commit

Permalink
docs(*/reference): add links to code samples (#2305)
Browse files Browse the repository at this point in the history
  • Loading branch information
qbzzt authored Feb 23, 2024
1 parent cd7c92e commit df118eb
Show file tree
Hide file tree
Showing 11 changed files with 128 additions and 3 deletions.
2 changes: 2 additions & 0 deletions docs/pages/store/reference/misc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
9 changes: 8 additions & 1 deletion docs/pages/store/reference/store-core.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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._
Expand Down
3 changes: 2 additions & 1 deletion docs/pages/store/reference/store-hook.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 4 additions & 0 deletions docs/pages/store/reference/store.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -503,6 +505,8 @@ function registerTable(

#### registerStoreHook

[Usage Sample](/store/store-hooks)

```solidity
function registerStoreHook(ResourceId tableId, IStoreHook hookAddress, uint8 enabledHooksBitmap) external;
```
Expand Down
3 changes: 2 additions & 1 deletion docs/pages/world/reference/delegation-external.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
10 changes: 10 additions & 0 deletions docs/pages/world/reference/internal/init-module-implementation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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._
Expand Down Expand Up @@ -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_
Expand Down Expand Up @@ -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
Expand All @@ -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_
Expand All @@ -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_
Expand Down
2 changes: 2 additions & 0 deletions docs/pages/world/reference/internal/systemcall.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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._
Expand Down
2 changes: 2 additions & 0 deletions docs/pages/world/reference/resource-ids.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 16 additions & 0 deletions docs/pages/world/reference/world-external.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ function storeVersion() public pure returns (bytes32);

#### registerTable

[Usage Sample](/store/tables#manually-register-a-table)

```solidity
function registerTable(
ResourceId tableId,
Expand All @@ -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._
Expand All @@ -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._
Expand Down Expand Up @@ -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._
Expand Down Expand Up @@ -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_
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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_
Expand Down Expand Up @@ -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)._
Expand Down
2 changes: 2 additions & 0 deletions docs/pages/world/reference/world.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
78 changes: 78 additions & 0 deletions scripts/render-api-docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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", "");
},
},
Expand All @@ -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;
},
},
Expand All @@ -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;
},
},
Expand All @@ -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")
Expand All @@ -97,6 +109,7 @@ const PUBLIC_APIS: PublicApis = {
content = formatHeadings(content);
content = fixGithubLinks(content, "world");
content = fixInheritence(content);

return content;
},
},
Expand Down Expand Up @@ -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;
},
},
Expand Down Expand Up @@ -153,6 +168,7 @@ const PUBLIC_APIS: PublicApis = {
content = formatHeadings(content);
content = fixGithubLinks(content, "world");
content = fixInheritence(content);

return content;
},
},
Expand Down Expand Up @@ -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;
},
},
Expand All @@ -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");
Expand Down Expand Up @@ -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", "")
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
},
},
Expand Down Expand Up @@ -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
///////////////////////////////////////////////////////////////////////////////////////////////////////
Expand Down

0 comments on commit df118eb

Please sign in to comment.