repo-website-api-review

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/FormSchema/';

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

Verification Checklist

properties.ts

• All generics have modifier: 'extends' (extends unknown when the source has no constraint)
• 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