Reviewing API Documentation

This skill provides a systematic approach to reviewing API documentation routes for accuracy and consistency.

Review Process

Step 1: Compare with Source Code

For each documented API:

1. •Read the source file completely
2. •Compare function signatures - Must match exactly
3. •Verify types - Generics, parameters, return types
4. •Check JSDoc - Descriptions should match

Step 2: Check properties.ts

Verify each property:

• • Generic constraints match source code
• • Parameter types are accurate
• • Return type is correct
• • All href links are valid
• • No unused properties defined

Step 3: Check index.mdx

Verify content:

• • Front matter is complete (title, description, source, contributors)
• • Function signature matches source exactly
• • All generics documented
• • All parameters documented with correct headings (Parameters vs Properties)
• • Explanation references specific parameters/properties
• • Examples are realistic and follow conventions
• • Related section uses correct framework terminology

Step 4: Check Menu and Links

• • API listed in menu.md (alphabetical order)
• • All internal links work
• • Cross-package links use absolute paths
• • No broken links to types or functions

Common Issues to Find

Signature Mismatches

// Source code
export function validate(form: FormStore, config?: Config): void;

// ❌ Documentation shows different signature
const result = validate(form); // Missing config, wrong return

Missing Parameters

Documentation should include ALL parameters from source:

## Parameters

- `form` <Property {...properties.form} />
- `config` <Property {...properties.config} /> <!-- Don't forget optional params -->

Wrong Headings

Outdated Examples

Examples must work with current API:

// ❌ Old API usage
const form = createForm(schema);

// ✅ Current API
const form = createForm({ schema });

Framework Terminology

Type Links

// ❌ Wrong - using constraint type name
generics: [{ type: 'custom', name: 'RequiredPath' }];

// ✅ Correct - using parameter name
generics: [{ type: 'custom', name: 'TFieldPath' }];

Cross-Package Links

// ❌ Wrong - relative across packages
href: '../../../core/api/Schema/';

// ✅ Correct - absolute path
href: '/core/api/Schema/';

Verification Checklist

properties.ts

• • All generics have modifier: 'extends'
• • Custom types have valid href links
• • Property order: name, href, generics
• • No unused properties
• • Types match source exactly

index.mdx

• • Title matches API name exactly (case-sensitive)
• • Description ends with period
• • Source path is correct
• • Function signature code block matches source
• • Correct heading (Parameters/Properties)
• • Explanation references specific params/props
• • Returns section present (unless void or component)
• • Examples section present (unless component/type)
• • Related section uses correct framework terminology
• • No Types in Related section

Menu Integration

• • API listed in appropriate menu.md
• • Alphabetical order maintained
• • Link path matches folder structure

Link Validation

• • All href in properties.ts resolve
• • ApiList links are valid
• • Cross-framework links use absolute paths
• • External links (Valibot) use full URLs

Review Output Format

Document issues found:

## Review: createForm

### Issues Found

1. **Signature mismatch** (L15)
   - Source shows `config: FormConfig<TSchema>`
   - Docs show `config: Config`

2. **Missing parameter** (Parameters section)
   - `initialInput` not documented

3. **Broken link** (properties.ts L23)
   - `href: '../FormConfig/'` - FormConfig not documented

### Recommendations

- Update properties.ts with correct FormConfig type
- Add initialInput to Parameters section
- Create FormConfig type documentation