# TypeDoc Runner

Guide for generating frontend API documentation using TypeDoc.

## Overview

TypeDoc generates API documentation from TypeScript source code by analyzing type annotations and JSDoc comments.

## Prerequisites

### Check TypeScript Project

```javascript
// Verify TypeScript is used
const packageJson = JSON.parse(Read('package.json'));
const hasTypeScript = packageJson.devDependencies?.typescript ||
                      packageJson.dependencies?.typescript;

if (!hasTypeScript) {
  console.log('Not a TypeScript project. Skipping TypeDoc.');
  return;
}

// Check for tsconfig.json
const hasTsConfig = Glob('tsconfig.json').length > 0;
```

## Installation

### Install TypeDoc

```bash
npm install --save-dev typedoc typedoc-plugin-markdown
```

### Optional Plugins

```bash
# For better Markdown output
npm install --save-dev typedoc-plugin-markdown

# For README inclusion
npm install --save-dev typedoc-plugin-rename-defaults
```

## Configuration

### typedoc.json

Create `typedoc.json` in project root:

```json
{
  "entryPoints": ["./src/index.ts"],
  "entryPointStrategy": "expand",
  "out": ".workflow/.scratchpad/manual-{timestamp}/api-docs/frontend",
  "plugin": ["typedoc-plugin-markdown"],
  "exclude": [
    "**/node_modules/**",
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/tests/**"
  ],
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeInternal": true,
  "hideGenerator": true,
  "readme": "none",
  "categorizeByGroup": true,
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  }
}
```

### Alternative: CLI Options

```bash
npx typedoc \
  --entryPoints src/index.ts \
  --entryPointStrategy expand \
  --out api-docs/frontend \
  --plugin typedoc-plugin-markdown \
  --exclude "**/node_modules/**" \
  --exclude "**/*.test.ts" \
  --excludePrivate \
  --excludeProtected \
  --readme none
```

## Execution

### Basic Run

```javascript
async function runTypeDoc(workDir) {
  const outputDir = `${workDir}/api-docs/frontend`;

  // Create output directory
  Bash({ command: `mkdir -p "${outputDir}"` });

  // Run TypeDoc
  const result = Bash({
    command: `npx typedoc --out "${outputDir}" --plugin typedoc-plugin-markdown src/`,
    timeout: 120000  // 2 minutes
  });

  if (result.exitCode !== 0) {
    console.error('TypeDoc failed:', result.stderr);
    return { success: false, error: result.stderr };
  }

  // List generated files
  const files = Glob(`${outputDir}/**/*.md`);
  console.log(`Generated ${files.length} documentation files`);

  return { success: true, files };
}
```

### With Custom Entry Points

```javascript
async function runTypeDocCustom(workDir, entryPoints) {
  const outputDir = `${workDir}/api-docs/frontend`;

  // Build entry points string
  const entries = entryPoints.map(e => `--entryPoints "${e}"`).join(' ');

  const result = Bash({
    command: `npx typedoc ${entries} --out "${outputDir}" --plugin typedoc-plugin-markdown`,
    timeout: 120000
  });

  return { success: result.exitCode === 0 };
}

// Example: Document specific files
await runTypeDocCustom(workDir, [
  'src/api/index.ts',
  'src/hooks/index.ts',
  'src/utils/index.ts'
]);
```

## Output Structure

```
api-docs/frontend/
├── README.md                    # Index
├── modules.md                   # Module list
├── modules/
│   ├── api.md                   # API module
│   ├── hooks.md                 # Hooks module
│   └── utils.md                 # Utils module
├── classes/
│   ├── ApiClient.md             # Class documentation
│   └── ...
├── interfaces/
│   ├── Config.md                # Interface documentation
│   └── ...
└── functions/
    ├── formatDate.md            # Function documentation
    └── ...
```

## Integration with Manual

### Reading TypeDoc Output

```javascript
async function integrateTypeDocOutput(workDir) {
  const apiDocsDir = `${workDir}/api-docs/frontend`;
  const files = Glob(`${apiDocsDir}/**/*.md`);

  // Build API reference content
  let content = '## Frontend API Reference\n\n';

  // Add modules
  const modules = Glob(`${apiDocsDir}/modules/*.md`);
  for (const mod of modules) {
    const modContent = Read(mod);
    content += `### ${extractTitle(modContent)}\n\n`;
    content += summarizeModule(modContent);
  }

  // Add functions
  const functions = Glob(`${apiDocsDir}/functions/*.md`);
  content += '\n### Functions\n\n';
  for (const fn of functions) {
    const fnContent = Read(fn);
    content += formatFunctionDoc(fnContent);
  }

  // Add hooks
  const hooks = Glob(`${apiDocsDir}/functions/*Hook*.md`);
  if (hooks.length > 0) {
    content += '\n### Hooks\n\n';
    for (const hook of hooks) {
      const hookContent = Read(hook);
      content += formatHookDoc(hookContent);
    }
  }

  return content;
}
```

### Example Output Format

```markdown
## Frontend API Reference

### API Module

Functions for interacting with the backend API.

#### fetchProjects

```typescript
function fetchProjects(options?: FetchOptions): Promise<Project[]>
```

Fetches all projects for the current user.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| options | FetchOptions | Optional fetch configuration |

**Returns:** Promise<Project[]>

### Hooks

#### useProjects

```typescript
function useProjects(options?: UseProjectsOptions): UseProjectsResult
```

React hook for managing project data.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| options.status | string | Filter by project status |
| options.limit | number | Max projects to fetch |

**Returns:**

| Property | Type | Description |
|----------|------|-------------|
| projects | Project[] | Array of projects |
| loading | boolean | Loading state |
| error | Error \| null | Error if failed |
| refetch | () => void | Refresh data |
```

## Troubleshooting

### Common Issues

#### "Cannot find module 'typescript'"

```bash
npm install --save-dev typescript
```

#### "No entry points found"

Ensure entry points exist:

```bash
# Check entry points
ls src/index.ts

# Or use glob pattern
npx typedoc --entryPoints "src/**/*.ts"
```

#### "Unsupported TypeScript version"

```bash
# Check TypeDoc compatibility
npm info typedoc peerDependencies

# Install compatible version
npm install --save-dev typedoc@0.25.x
```

### Debugging

```bash
# Verbose output
npx typedoc --logLevel Verbose src/

# Show warnings
npx typedoc --treatWarningsAsErrors src/
```

## Best Practices

### Document Exports Only

```typescript
// Good: Public API documented
/**
 * Fetches projects from the API.
 * @param options - Fetch options
 * @returns Promise resolving to projects
 */
export function fetchProjects(options?: FetchOptions): Promise<Project[]> {
  // ...
}

// Internal: Not documented
function internalHelper() {
  // ...
}
```

### Use JSDoc Comments

```typescript
/**
 * User hook for managing authentication state.
 *
 * @example
 * ```tsx
 * const { user, login, logout } = useAuth();
 * ```
 *
 * @returns Authentication state and methods
 */
export function useAuth(): AuthResult {
  // ...
}
```

### Define Types Properly

```typescript
/**
 * Configuration for the API client.
 */
export interface ApiConfig {
  /** API base URL */
  baseUrl: string;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Custom headers to include */
  headers?: Record<string, string>;
}
```
