write-api-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing API Reference Pages

编写API参考页面

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.

生成一份针对单个API层面（函数、组件、文件约定、指令或配置选项）的参考文档。页面应简洁、易于浏览且以示例为导向。

每个页面仅记录一个API。如果API包含子方法（如

cookies.set()

），则在同一页面中记录。如果两个API相互独立，则分别使用不同页面。

Structure

结构

Identify which category the API belongs to, then follow the corresponding template.

确定API所属的类别，然后遵循对应的模板。

类别

Function (
```
cookies
```
,
```
fetch
```
,
```
generateStaticParams
```
): signature, params/returns, methods table, examples
Component (
```
Link
```
,
```
Image
```
,
```
Script
```
): props summary table, individual prop docs, examples
File convention (
```
page
```
,
```
layout
```
,
```
route
```
): definition, code showing the convention, props, behavior, examples
Directive (
```
use client
```
,
```
use cache
```
): definition, usage, serialization/boundary rules, reference
Config option (
```
basePath
```
,
```
images
```
, etc.): definition, config code, behavioral sections

函数（
```
cookies
```
、
```
fetch
```
、
```
generateStaticParams
```
）：签名、参数/返回值、方法表格、示例
组件（
```
Link
```
、
```
Image
```
、
```
Script
```
）：属性汇总表格、单个属性文档、示例
文件约定（
```
page
```
、
```
layout
```
、
```
route
```
）：定义、展示约定的代码、属性、行为、示例
指令（
```
use client
```
、
```
use cache
```
）：定义、用法、序列化/边界规则、参考
配置选项（
```
basePath
```
、
```
images
```
等）：定义、配置代码、行为章节

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
```

markdown

---
title: {API名称}
description: {API名称} {函数|组件|文件约定|指令|配置选项}的API参考文档。
---

{一句话定义该API的功能及使用场景。}

```tsx filename="path/to/file.tsx" switcher
// 最简可用示例
```

```jsx filename="path/to/file.js" switcher
// 同示例的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.}

{针对函数：方法/参数表格、返回类型。} {针对组件：属性汇总表格，然后是

#### propName

子章节。} {针对文件约定：

### 属性

及

#### propName

子章节。} {针对指令：用法规则和序列化约束。} {针对配置：选项表格或单个选项文档。}

{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

// Complete working example

jsx

// Same example in JS

{简短背景介绍，1-2句话。}

tsx

// 完整可用示例

jsx

// 同示例的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.

版本	变更内容
`vX.Y.Z`	{变更详情。}


**类别特定说明：**

- **函数：**以函数签名开头，异步函数需添加`await`。如果返回值包含方法（如`cookies`），则在表格中记录方法。如有必要，单独用表格记录选项。
- **组件：**以属性汇总表格开头（`| 属性 | 示例 | 类型 | 是否必填 |`）。然后在`#### propName`下记录每个属性的描述、代码示例及有用的取值表格。
- **文件约定：**展示包含TypeScript类型的默认导出签名。在`#### propName`下记录每个属性（`params`、`searchParams`等），并附上路由/URL/取值示例表格。
- **指令：**无需`## 参考`章节，改用`## 用法`章节展示正确的使用位置。记录序列化约束和边界规则。
- **配置选项：**展示`next.config.ts`代码片段。针对每个行为方面使用子章节。

Rules

规则

Lead with what it does. First sentence defines the API. No preamble.
Show working code immediately. A minimal usage example appears right after the opening sentence, before
```
## Reference
```
.
Use
switcher
for tsx/jsx pairs. Always include both. Always include
```
filename="path/to/file.ext"
```
.
Use
highlight={n}
for key lines. Highlight the line that demonstrates the API being documented.
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.
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:".
Examples section uses
### Example Name
subsections. Each example solves one specific use case.
Version History table at the end. Include when the API has changed across versions. Omit for new APIs.
No em dashes. Use periods, commas, or parentheses instead.
Mechanical, observable language. Describe what happens, not how it feels. "Returns an object" not "gives you an object".
Link to related docs with relative paths. Use
```
/docs/app/...
```
format.
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"

**开门见山说明功能。**第一句话定义API，无需开场白。
**立即展示可用代码。**在开篇句子后、
```
## 参考
```
之前，立即放置最简使用示例。
**为tsx/jsx示例使用
```
switcher
```
。**始终同时包含两种版本。始终添加
```
filename="path/to/file.ext"
```
。
**使用
```
highlight={n}
```
标记关键行。**高亮展示正在记录的API的代码行。
**简单API用表格，复杂API用子章节。**如果某个属性/参数仅需类型和一行描述，使用表格行。如果需要代码示例或多个取值，使用
```
####
```
子章节。
**行为说明使用
```
> **补充说明：**
```
或
```
## 补充说明
```
格式。**简短说明（1-3条项目符号）使用块引用格式。较长章节使用标题格式。不要使用“注意：”或“警告：”。
**示例章节使用
```
### 示例名称
```
子章节。**每个示例解决一个特定的使用场景。
**末尾添加版本历史表格。**如果API在不同版本中有变更，需包含该表格。新API可省略。
**不要使用破折号。**改用句号、逗号或括号。
**使用客观、可观察的语言。**描述实际发生的情况，而非主观感受。例如“返回一个对象”而非“给你一个对象”。
**使用相对路径链接到相关文档。**采用
```
/docs/app/...
```
格式。
**不要夸大或解释合理性。**不要使用“强大的”、“轻松地”、“简单地”等词汇。仅说明API的功能。

错误示例	正确示例
"这个强大的函数让你轻松管理cookies"	" `cookies` 是一个异步函数，可在Server Components中读取HTTP请求cookies"
"你可以方便地访问..."	"返回一个包含...的对象"
"处理导航的最佳方式"	" `<Link>` 扩展了HTML `<a>` 元素，提供预取和客户端导航功能"

Workflow

工作流程

Ask for reference material. Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
Identify the API category (function, component, file convention, directive, config).
Research the implementation. Read the source code to understand params, return types, edge cases, and defaults.
Check e2e tests. Search
```
test/
```
for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
Check existing related docs for linking opportunities and to avoid duplication.
Write using the appropriate category template. Follow the rules above.
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.

**索要参考资料。**询问用户是否有任何RFC、PR、设计文档或其他应纳入文档的背景信息。
确定API类别（函数、组件、文件约定、指令、配置）。
**研究实现细节。**阅读源代码，了解参数、返回类型、边缘情况和默认值。
**检查端到端测试。**在
```
test/
```
目录中搜索测试该API的用例，找到实际使用模式、边缘情况和预期行为。
检查现有相关文档，寻找链接机会并避免重复。
**使用对应类别的模板编写。**遵循上述规则。
**对照规则审核。**验证：开篇一句话、立即展示代码示例、正确使用
```
switcher
```
/
```
filename
```
、表格与子章节的选择、“补充说明”格式、无破折号、客观语言。

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

开始编写前，请阅读

docs/01-app/03-api-reference/

中的以下页面，它们展示了上述模式。

```
04-functions/cookies.mdx
```
- 包含方法表格、选项表格和行为说明的函数文档
```
03-file-conventions/page.mdx
```
- 包含属性子章节和路由/URL/取值表格的文件约定文档
```
02-components/link.mdx
```
- 包含属性汇总表格和详细属性文档的组件文档
```
01-directives/use-client.mdx
```
- 包含用法章节和序列化规则的指令文档
```
04-functions/fetch.mdx
```
- 包含故障排除章节和版本历史的函数文档