# Codocma

_Solana Program Docs, Generated by Codama_

This package provides a Solana program documentation renderer for [Codama](https://github.com/codama-idl/codama) that generates markdown or JSON documentation from Solana program IDL files.

This tool is in beta so please report any issues or feedback.

Documentation is generated from the IDL, so for best results it's important to document your Shank Macros well (or add visitors to your `renderDocsVisitor` (see example below)).

## Installation

```bash
# Beta version
pnpm add codocma@beta
```

## Usage

### Basic Usage

```typescript
import { renderDocsVisitor } from 'codocma';
import { rootNode } from '@codama/nodes';
import { visit } from '@codama/visitors-core';

// Create or load your Codama root node
const root = rootNode(/* ... */);

// Generate documentation
visit(root, renderDocsVisitor('./docs'));
```

For more examples of integration with Codama, check out the [Codama GitHub](https://github.com/codama-idl/codama) repository.

### Example Output

- [Raydium Program](./test/e2e/raydium/docs/raydiumamm-program.md)
- [Raydium Program JSON](./test/e2e/raydium/docs/raydiumamm-program.json)

### Configuration Options

The renderer accepts various options to customize the output:

```typescript
visit(
    root,
    renderDocsVisitor('./docs', {
        // Output format: 'markdown' (default) or 'json'
        format: 'markdown',

        // Sections to include: 'instructions', 'accounts', 'types', 'errors', 'pdas'
        sections: ['instructions', 'accounts', 'types', 'errors', 'pdas'],

        // Custom program ID (defaults to the publicKey in IDL)
        programId: 'MyProgram11111111111111111111111111111111111',

        // Include table of contents
        includeTableOfContents: true,

        // Include discriminator values
        includeDiscriminators: true,

        // Delete existing docs folder before generating
        deleteFolderBeforeRendering: false,

        // Custom descriptions for various components
        customDescriptions: {
            instructions: {
                initialize: 'Initialize the program state',
                transfer: 'Transfer tokens between accounts',
            },
            accounts: {
                userAccount: 'Stores user information and settings',
                vaultAccount: 'Holds program funds',
            },
            types: {
                UserRole: 'Defines the role of a user in the system',
            },
            errors: {
                InsufficientFunds: 'Thrown when an account has insufficient funds for the operation',
            },
            pdas: {
                vaultPda: 'The program-derived address for the vault',
            },
        },
    }),
);
```

### Output Format

The renderer generates comprehensive documentation including:

1. **Program Overview** - Program ID and general information
2. **Instructions** - All program instructions with:
    - Description
    - Discriminator values
    - Parameters (arguments) with detailed type information
    - Required accounts with their permissions (signer/writable status)
3. **Accounts** - All program accounts with:
    - Description
    - Discriminator values
    - Field definitions with nested type resolution
    - Link to PDA derivation if available
4. **Types** - Custom types defined in the program:
    - **Enums** with:
        - Variant names and descriptions
        - Discriminator values for each variant
        - Fields for struct and tuple variants
        - Size information
    - **Structs** with:
        - Field names, types, and descriptions
        - Support for complex nested types
    - Support for many Codama type nodes including (e.g., arrays, options, maps, etc.)
5. **Errors** - Program errors with codes and descriptions
6. **PDAs** - Program Derived Addresses with:
    - Description
    - Seeds configuration
    - Associated program ID

### JSON Output

When using `format: 'json'`, the renderer outputs a structured JSON file:

```json
{
  "programName": "My Program",
  "programId": "MyProgram11111111111111111111111111111111111",
  "instructions": [...],
  "accounts": [...],
  "types": [...],
  "errors": [...],
  "pdas": [...]
}
```

This format is useful for generating documentation websites or integrating with other tools.

## Architecture

Fragments (src/fragments/):

- Template system - Reusable, configurable UI components
- Rendering logic - How to format specific pieces (headers, tables, etc.)
- Presentation layer - Controls styling, layout, formatting

Collectors (src/collectors/):

- Data extraction - Parse AST nodes into structured data
- Business logic - Handle discriminators, descriptions, field extraction
- Data transformation - Convert Codama nodes → TypeScript interfaces

Generators (src/generators/):

- Orchestration - Coordinate fragments to build complete sections
- Content assembly - Combine multiple fragments into cohesive output
- High-level layout - Organize sections, TOC, overall document structure

Data flow:

```bash
Codama AST Nodes → Collectors → Structured Data → Generators (using Fragments) → Final Output
```

## Contributing

Submit an issue or PR.