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:

Read the source file completely
Compare function signatures - Must match exactly
Verify types - Generics, parameters, return types
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

| API Type | Heading | | ---------- | --------------- | | Functions | ## Parameters | | Components | ## Properties |

Outdated Examples

Examples must work with current API:

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

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

Framework Terminology

| Framework | Related Section Heading | | --------- | ----------------------- | | Solid | ### Primitives | | Qwik | ### Hooks | | Preact | ### Hooks | | Vue | ### Composables | | Svelte | ### Runes |

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