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

typescript
1// Source code
2export function validate(form: FormStore, config?: Config): void;
3
4// ❌ Documentation shows different signature
5const result = validate(form); // Missing config, wrong return

Missing Parameters

Documentation should include ALL parameters from source:

mdx
1## Parameters
2
3- `form` <Property {...properties.form} />
4- `config` <Property {...properties.config} /> <!-- Don't forget optional params -->

Wrong Headings

Outdated Examples

Examples must work with current API:

typescript
1// ❌ Old API usage
2const form = createForm(schema);
3
4// ✅ Current API
5const form = createForm({ schema });

Framework Terminology

Type Links

typescript
1// ❌ Wrong - using constraint type name
2generics: [{ type: 'custom', name: 'RequiredPath' }];
3
4// ✅ Correct - using parameter name
5generics: [{ type: 'custom', name: 'TFieldPath' }];

Cross-Package Links

typescript
1// ❌ Wrong - relative across packages
2href: '../../../core/api/Schema/';
3
4// ✅ Correct - absolute path
5href: '/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:

markdown
1## Review: createForm
2
3### Issues Found
4
51. **Signature mismatch** (L15)
6   - Source shows `config: FormConfig<TSchema>`
7   - Docs show `config: Config`
8
92. **Missing parameter** (Parameters section)
10   - `initialInput` not documented
11
123. **Broken link** (properties.ts L23)
13   - `href: '../FormConfig/'` - FormConfig not documented
14
15### Recommendations
16
17- Update properties.ts with correct FormConfig type
18- Add initialInput to Parameters section
19- Create FormConfig type documentation