Updating API Documentation

Guide for syncing API docs with source code changes.

Prerequisite: Read the repo-website-api-create skill for properties.ts and index.mdx patterns.

When to Update

Update documentation when source code changes:

• Function signatures (parameters, generics, return types)

• Interface properties

• JSDoc descriptions or hints

• Behavior changes affecting examples

Do NOT update for: Internal implementation changes (~run method), test changes, non-JSDoc comments.

Process

• Read full source file - Don't just look at diff; understand complete current state

• Identify changes - Categorize as addition, removal, or modification

• Update properties.ts

• Match types exactly to source

• Update index.mdx

• Signature, generics, parameters, examples

• Update related files - Type docs, menu.md if renamed

Common Change Types

New Parameter Added

// Before: one overload export function action<TInput>(requirement: TRequirement): Action<...>;

// After: two overloads (message is optional) export function action<TInput>(requirement: TRequirement): Action<..., undefined>; export function action<TInput, TMessage>(requirement: TRequirement, message: TMessage): Action<..., TMessage>;

Update:

• Add TMessage generic to properties.ts

• Add message parameter to properties.ts

• Update signature in index.mdx

• Add generic and parameter documentation

• Update examples to show new parameter

Parameter Removed (Breaking)

• Remove from properties.ts

• Update signature in index.mdx

• Remove from Parameters section

• Update all examples

• Consider adding migration note in Explanation

Type Constraint Changed

// Before TRequirement extends number

// After TRequirement extends number | string

Update:

• Update type in properties.ts

• Update Explanation to mention both types

• Add examples for new type usage

Interface Property Added

• Update type documentation in (types)/TypeName/

• Add new property to properties.ts

• Document in Definition section

Function Renamed

• Rename folder

• Update all references in files

• Update menu.md (maintain alphabetical order)

• Update cross-references in related API docs

• Consider redirect if widely used

Deprecation

Add notice at top of index.mdx (import Link from ~/components ):

⚠️ Deprecated: Use <Link href="../newFunction/">`newFunction`</Link> instead. Will be removed in v2.0.

New Helper Type Introduced

When source introduces a type alias:

// Before: TInput extends string | unknown[] // After: TInput extends LengthInput

• Update properties.ts to reference new type with href

• Create documentation for the new type in (types)/

• Update explanation if supported types changed

Multiple Overloads Added (Sync/Async)

When sync and async variants are added:

• Update signature to show general pattern or both overloads

• Add explanation about sync vs async usage

• Add examples for both use cases

• Update Related section for async schemas if relevant

Related Files to Update

When a function changes, check:

• Type docs - If interfaces changed ((types)/TypeName/ )

• Related API docs - Other APIs that reference this function in their Related section

• Guide files - If usage patterns changed significantly

• menu.md - If function renamed or moved

Verification

After updating, verify:

• All types match source exactly

• Function signature matches source

• All examples work with new API

• All href links are valid

• Related type docs updated if interfaces changed

• menu.md updated if renamed

• Related API docs updated (their Related sections)

Best Practices

• Read full source file - Don't just look at diff

• Update incrementally - properties.ts → index.mdx → related files

• Don't over-document internals - Only user-facing changes need docs

• Preserve example quality - Keep realistic, demonstrate best practices

• Check related APIs - They may reference the changed function

When to Ask for Help

• Major breaking changes (complete signature overhaul)

• Complex generic constraint changes

• Unclear intent from source changes

• Many related files affected

• Need to document migration path

Quick Reference

Change Files to Update

New parameter properties.ts , index.mdx (signature, generics, params, examples)

Removed parameter properties.ts , index.mdx

Type change properties.ts , index.mdx (explanation, examples)

Interface change (types)/TypeName/properties.ts , (types)/TypeName/index.mdx

Renamed function Folder name, all files, menu.md , cross-references

Deprecation index.mdx (add warning)