write-api-reference

# Writing API Reference Pages ## Goal Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven. Each page documents **one API**. If the API has sub-methods (like `cookies.set()`), document them on the same page. If two APIs are independent, they get separate pages. ## Structure Identify which category the API belongs to, then follow the corresponding template. ### Categories 1. **Function** (`cookies`, `fetch`, `generateStaticParams`): signature, params/returns, methods table, examples 2. **Component** (`Link`, `Image`, `Script`): props summary table, individual prop docs, examples 3. **File convention** (`page`, `layout`, `route`): definition, code showing the convention, props, behavior, examples 4. **Directive** (`use client`, `use cache`): definition, usage, serialization/boundary rules, reference 5. **Config option** (`basePath`, `images`, etc.): definition, config code, behavioral sections ### Template ````markdown --- title: {API name} description: {API Reference for the {API name} {function|component|file convention|directive|config option}.} --- {One sentence defining what it does and where it's used.} ```tsx filename="path/to/file.tsx" switcher // Minimal working usage ``` ```jsx filename="path/to/file.js" switcher // Same example in JS ``` ## Reference {For functions: methods/params table, return type.} {For components: props summary table, then `#### propName` subsections.} {For file conventions: `### Props` with `#### propName` subsections.} {For directives: usage rules and serialization constraints.} {For config: options table or individual option docs.} ### {Subsection name} {Description + code example + table of values where applicable.} ## Good to know - {Default behavior or implicit effects.} - {Caveats, limitations, or version-specific notes.} - {Edge cases the developer should be aware of.} ## Examples ### {Example name} {Brief context, 1-2 sentences.} ```tsx filename="path/to/file.tsx" switcher // Complete working example ``` ```jsx filename="path/to/file.js" switcher // Same example in JS ``` ## Version History | Version | Changes | | -------- | --------------- | | `vX.Y.Z` | {What changed.} | ```` **Category-specific notes:** - **Functions**: Lead with the function signature and `await` if async. Document methods in a table if the return value has methods (like `cookies`). Document options in a separate table if applicable. - **Components**: Start with a props summary table (`| Prop | Example | Type | Required |`). Then document each prop under `#### propName` with description, code example, and value table where useful. - **File conventions**: Show the default export signature with TypeScript types. Document each prop (`params`, `searchParams`, etc.) under `#### propName` with a route/URL/value example table. - **Directives**: No `## Reference` section. Use `## Usage` instead, showing correct placement. Document serialization constraints and boundary rules. - **Config options**: Show the `next.config.ts` snippet. Use subsections for each behavioral aspect. ## Rules 1. **Lead with what it does.** First sentence defines the API. No preamble. 2. **Show working code immediately.** A minimal usage example appears right after the opening sentence, before `## Reference`. 3. **Use `switcher` for tsx/jsx pairs.** Always include both. Always include `filename="path/to/file.ext"`. 4. **Use `highlight={n}` for key lines.** Highlight the line that demonstrates the API being documented. 5. **Tables for simple APIs, subsections for complex ones.** If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a `####` subsection. 6. **Behavior section uses `> **Good to know**:`or`## Good to know`.** Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:". 7. **Examples section uses `### Example Name` subsections.** Each example solves one specific use case. 8. **Version History table at the end.** Include when the API has changed across versions. Omit for new APIs. 9. **No em dashes.** Use periods, commas, or parentheses instead. 10. **Mechanical, observable language.** Describe what happens, not how it feels. "Returns an object" not "gives you an object". 11. **Link to related docs with relative paths.** Use `/docs/app/...` format. 12. **No selling or justifying.** No "powerful", "easily", "simply". State what the API does. | Don't | Do | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | "This powerful function lets you easily manage cookies" | "`cookies` is an async function that reads HTTP request cookies in Server Components" | | "You can conveniently access..." | "Returns an object containing..." | | "The best way to handle navigation" | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" | 13. **Bridge new framework terms with legacy or generic vocabulary.** When the API renames or differentiates from a prior concept (Pages-era term, generic web term, REST vocabulary), include one such synonym in the frontmatter `description` and once in prose. Example: `description: "Use Dynamic Segments to read URL parameters and generate routes from dynamic data."` mentions "URL parameters" alongside "Dynamic Segments". One synonym, folded into natural prose. No separate "Synonyms" or "Also known as" section, no keyword stuffing. Goal: preserve discoverability for users still searching the old vocabulary even when the framework has moved on. | Don't | Do | | ---------------------------------- | ------------------------------------------------------------------------------------ | | "Learn how to use Route Handlers" | "Build API endpoints with Route Handlers, the App Router replacement for API Routes" | | "Configure dynamic route segments" | "Read URL parameters from dynamic route segments" | ## Workflow 1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc. 2. **Identify the API category** (function, component, file convention, directive, config). 3. **Research the implementation.** Read the source code to understand params, return types, edge cases, and defaults. 4. **Check e2e tests.** Search `test/` for tests exercising the API to find real usage patterns, edge cases, and expected behavior. 5. **Check existing related docs** for linking opportunities and to avoid duplication. 6. **Write using the appropriate category template.** Follow the rules above. 7. **Review against the rules.** Verify: one sentence opener, immediate code example, correct `switcher`/`filename` usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language. ## References Read these pages in `docs/01-app/03-api-reference/` before writing. They demonstrate the patterns above. - `04-functions/cookies.mdx` - Function with methods table, options table, and behavior notes - `03-file-conventions/page.mdx` - File convention with props subsections and route/URL/value tables - `02-components/link.mdx` - Component with props summary table and detailed per-prop docs - `01-directives/use-client.mdx` - Directive with usage section and serialization rules - `04-functions/fetch.mdx` - Function with troubleshooting section and version history