Skip to content

feat: nodeDocs generation from spec #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mikhd wants to merge 3 commits into
base: spec-generators-nodes-docs
Choose a base branch
from
Draft

feat: nodeDocs generation from spec #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3237cfe
feat: initial spec-generator for nodes docs
mikhd Jul 16, 2026
db2b13f
feat: generate docs
mikhd Aug 7, 2026
d23a411
feat: tsdoc extraction via typedoc
mikhd Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 1 addition & 79 deletions packages/nodes/docs/AccountNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,81 +1,3 @@
# `AccountNode`

This node defines an on-chain account. It is characterized by its name, data structure, and optional attributes such as PDA definition and account discriminators.

![Diagram](https://github.com/codama-idl/codama/assets/3642397/77974dad-212e-49b1-8e41-5d466c273a02)

## Attributes

### Data

| Attribute | Type | Description |
| --------- | ----------------- | ----------------------------------------------------------------------------------- |
| `kind` | `"accountNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the account. |
| `docs` | `string[]` | Markdown documentation for the account. |
| `size` | `number` | (Optional) The size of the account in bytes, if the account's data length is fixed. |

### Children

| Attribute | Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data` | [`NestedTypeNode`](./typeNodes/NestedTypeNode.md)<[`StructTypeNode`](./typeNodes/StructTypeNode.md)> | The type node that describes the account's data. Note that it must be a struct so we can access its fields via other nodes. |
| `pda` | [`PdaLinkNode`](./linkNodes/PdaLinkNode.md) | (Optional) The link node that describes the account's PDA, if its address is derived from one. |
| `discriminators` | [`DiscriminatorNode`](./discriminatorNodes/README.md)[] | (Optional) The nodes that distinguish this account from others in the program. If multiple discriminators are provided, they are combined using a logical AND operation. |

## Functions

### `accountNode(input)`

Helper function that creates a `AccountNode` object from an input object.

```ts
const node = accountNode({
name: 'myCounter',
data: structTypeNode([
structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() }),
structFieldTypeNode({ name: 'value', type: numberTypeNode('u64') }),
]),
});
```

## Examples

### A fixed-size account

```ts
const node = accountNode({
name: 'token',
data: structTypeNode([
structFieldTypeNode({ name: 'mint', type: publicKeyTypeNode() }),
structFieldTypeNode({ name: 'owner', type: publicKeyTypeNode() }),
structFieldTypeNode({ name: 'amount', type: numberTypeNode('u64') }),
]),
discriminators: [sizeDiscriminatorNode(72)],
size: 72,
});
```

### An account with a linked PDA

```ts
programNode({
name: 'myProgram',
accounts: [
accountNode({
name: 'token',
data: structTypeNode([structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() })]),
pda: pdaLinkNode('myPda'),
}),
],
pdas: [
pdaNode({
name: 'myPda',
seeds: [
constantPdaSeedNodeFromString('utf8', 'token'),
variablePdaSeedNode('authority', publicKeyTypeNode()),
],
}),
],
});
```
See the [`AccountNode` specification](https://github.com/codama-idl/spec/blob/main/docs/AccountNode.md).
51 changes: 1 addition & 50 deletions packages/nodes/docs/ConstantNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,3 @@
# `ConstantNode`

This node represents a program-level constant with a name, type, and value.

## Attributes

### Data

| Attribute | Type | Description |
| --------- | ----------------- | ---------------------------------------- |
| `kind` | `"constantNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the constant. |
| `docs` | `string[]` | Markdown documentation for the constant. |

### Children

| Attribute | Type | Description |
| --------- | ------------------------------------- | ------------------------------- |
| `type` | [`TypeNode`](./typeNodes/README.md) | The type of the constant value. |
| `value` | [`ValueNode`](./valueNodes/README.md) | The constant value. |

## Functions

### `constantNode(name, type, value, docs?)`

Helper function that creates a `ConstantNode` object from its attributes.

```ts
const node = constantNode('maxSize', numberTypeNode('u64'), numberValueNode(1000));
```

## Examples

### Numeric Constant

```ts
const node = constantNode('maxSize', numberTypeNode('u32'), numberValueNode(100));
```

### Bytes Constant

```ts
const node = constantNode('seedPrefix', bytesTypeNode(), bytesValueNode('base16', '74657374'));
```

### With Documentation

```ts
const node = constantNode('maxItems', numberTypeNode('u64'), numberValueNode(1000), [
'The maximum number of items allowed.',
]);
```
See the [`ConstantNode` specification](https://github.com/codama-idl/spec/blob/main/docs/ConstantNode.md).
37 changes: 1 addition & 36 deletions packages/nodes/docs/DefinedTypeNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,3 @@
# `DefinedTypeNode`

This node defines a named type that can be reused in other types using a [`DefinedTypeLinkNode`](./linkNodes/DefinedTypeLinkNode.md).

![Diagram](https://github.com/codama-idl/codama/assets/3642397/6049cf77-9a70-4915-8276-dd571d2f8828)

## Attributes

### Data

| Attribute | Type | Description |
| --------- | ------------------- | ------------------------------------ |
| `kind` | `"definedTypeNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the reusable type. |
| `docs` | `string[]` | Markdown documentation for the type. |

### Children

| Attribute | Type | Description |
| --------- | ----------------------------------- | ----------------------------- |
| `type` | [`TypeNode`](./typeNodes/README.md) | The concrete type definition. |

## Functions

### `definedTypeNode(input)`

Helper function that creates a `DefinedTypeNode` object from an input object.

```ts
const node = definedTypeNode({
name: 'person',
docs: ['This type describes a Person.'],
type: structTypeNode([
structFieldTypeNode({ name: 'name', type: stringTypeNode('utf8') }),
structFieldTypeNode({ name: 'age', type: numberTypeNode('u8') }),
]),
});
```
See the [`DefinedTypeNode` specification](https://github.com/codama-idl/spec/blob/main/docs/DefinedTypeNode.md).
34 changes: 1 addition & 33 deletions packages/nodes/docs/ErrorNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,3 @@
# `ErrorNode`

This node defines an error that can be returned by a program.

![Diagram](https://github.com/codama-idl/codama/assets/3642397/0bde98ea-0327-404b-bf38-137d105826b0)

## Attributes

### Data

| Attribute | Type | Description |
| --------- | ----------------- | ------------------------------------------------ |
| `kind` | `"errorNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the error. |
| `code` | `number` | The error code. |
| `message` | `string` | A human-friendly message describing the error. |
| `docs` | `string[]` | Additional Markdown documentation for the error. |

### Children

_This node has no children._

## Functions

### `errorNode(input)`

Helper function that creates a `ErrorNode` object from an input object.

```ts
const node = errorNode({
name: 'invalidAmountArgument',
code: 1,
message: 'The amount argument is invalid.',
});
```
See the [`ErrorNode` specification](https://github.com/codama-idl/spec/blob/main/docs/ErrorNode.md).
65 changes: 1 addition & 64 deletions packages/nodes/docs/EventNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,3 @@
# `EventNode`

This node represents an event emitted by a program.

## Attributes

### Data

| Attribute | Type | Description |
| --------- | ----------------- | ------------------------------------------------ |
| `kind` | `"eventNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the event. |
| `docs` | `string[]` | Additional Markdown documentation for the event. |

### Children

| Attribute | Type | Description |
| ---------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | [`TypeNode`](./typeNodes/README.md) | The type node that describes the event payload. |
| `discriminators` | [`DiscriminatorNode`](./discriminatorNodes/README.md)[] | (Optional) The nodes that distinguish this event from others in the program. If multiple discriminators are provided, they are combined using a logical AND operation. |

## Functions

### `eventNode(input)`

Helper function that creates an `EventNode` object from an input object.

```ts
const node = eventNode({
name: 'transferEvent',
data: structTypeNode([
structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() }),
structFieldTypeNode({ name: 'amount', type: numberTypeNode('u64') }),
]),
});
```

## Examples

### An event with a struct payload

```ts
eventNode({
name: 'transferEvent',
data: structTypeNode([
structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() }),
structFieldTypeNode({ name: 'amount', type: numberTypeNode('u64') }),
]),
});
```

### An event with a hidden prefix discriminator

```ts
eventNode({
name: 'transferEvent',
data: hiddenPrefixTypeNode(structTypeNode([structFieldTypeNode({ name: 'amount', type: numberTypeNode('u64') })]), [
constantValueNode(fixedSizeTypeNode(bytesTypeNode(), 8), bytesValueNode('base16', '0102030405060708')),
]),
discriminators: [
constantDiscriminatorNode(
constantValueNode(fixedSizeTypeNode(bytesTypeNode(), 8), bytesValueNode('base16', '0102030405060708')),
),
],
});
```
See the [`EventNode` specification](https://github.com/codama-idl/spec/blob/main/docs/EventNode.md).
63 changes: 1 addition & 62 deletions packages/nodes/docs/InstructionAccountNode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,3 @@
# `InstructionAccountNode`

This node defines an account used by an instruction. It is characterized by its name and various requirements such as whether it needs to be writable or a signer.

![Diagram](https://github.com/codama-idl/codama/assets/3642397/4656a08b-2f89-49c2-b428-5378cb1a0b9e)

## Attributes

### Data

| Attribute | Type | Description |
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `kind` | `"instructionAccountNode"` | The node discriminator. |
| `name` | `CamelCaseString` | The name of the instruction account. |
| `isWritable` | `boolean` | Whether of not the account needs to be writable. |
| `isSigner` | `boolean` \| `"either"` | Whether or not the account needs to be a signer. If the value `"either"` is provided, the account can be either a signer or not depending on the context. |
| `isOptional` | `boolean` | (Optional) Whether or not the account is optional. If this is `true`, the account should be handled as an optional account according to the `optionalAccountStrategy` attribute of the [`InstructionNode`.](./InstructionNode.md) Defaults to `false`. |
| `docs` | `string[]` | Markdown documentation for the instruction account. |

### Children

| Attribute | Type | Description |
| -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `defaultValue` | [`InstructionInputValueNode`](./contextualValueNodes/InstructionInputValueNode.md) | (Optional) A default value for the account should this account not be provided when constructing the instruction. |

## Functions

### `instructionAccountNode(input)`

Helper function that creates a `InstructionAccountNode` object from an input object.

```ts
const node = instructionAccountNode({
name: 'authority',
isWritable: false,
isSigner: true,
docs: ['This account that has the authority to perform this instruction.'],
});
```

## Examples

### An optional account

```ts
instructionAccountNode({
name: 'freezeAuthority',
isWritable: false,
isSigner: false,
isOptional: true,
docs: ['The freeze authority to set on the asset, if any.'],
});
```

### An optional signer account

```ts
instructionAccountNode({
name: 'owner',
isWritable: true,
isSigner: 'either',
docs: ['The owner of the asset. The owner must only sign the transaction if the asset is being updated.'],
});
```
See the [`InstructionAccountNode` specification](https://github.com/codama-idl/spec/blob/main/docs/InstructionAccountNode.md).
Loading
Loading