reference-docs

参考文档模式

参考文档以信息为导向，旨在帮助有经验的用户快速查找精确的技术细节。本技能提供编写清晰、便于浏览的参考页面的模式。

依赖项： 始终将此技能与 docs-style 配合使用，以遵循核心写作原则。若要确认参考文档是否是合适的类型，而非教程、操作指南或说明，请参阅 docs-style/references/diataxis-compass.md。

目的和受众

• 对象： 寻找特定信息的有经验用户
• 目标： 快速查找技术细节
• 模式： 用于查找，而非学习
• 期望： 简洁、一致、完整

文档结构模板

创建参考文档时请使用此模板：

---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
---

# [Name]

Brief description (1-2 sentences). State what it is and its primary purpose.

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `param1` | `string` | Yes | What this parameter controls |
| `param2` | `number` | No | Optional behavior modification. Default: `10` |

## Returns

| Type | Description |
|------|-------------|
| `ReturnType` | What the function returns and when |

## Example

```language
import { symbolName } from 'package';

// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});

console.log(result);
// Expected output: { ... }

相关内容

• RelatedSymbol - 简要说明
• AnotherSymbol - 简要说明

## Writing Principles

### Describe, and Only Describe

Reference is austere, neutral, and authoritative — a map the reader can trust without independent verification. Its one job is to describe the machinery: commands, options, parameters, return values, limits, warnings. It does not instruct (that's How-To), teach (Tutorial), or argue (Explanation). When you feel the urge to explain *why* or walk the reader through a task, link out instead of inlining it; a digression interrupts and obscures the facts the reader came to consult.

### Structure Mirrors the Product

> "The structure of the documentation should mirror the structure of the product."

Organise reference so a reader can navigate the code and the docs in parallel — one reference entry per module, class, endpoint, or command, in the product's own order. Don't impose a narrative or thematic structure the product doesn't have; consistency of placement is what makes reference fast to consult.

### Brevity Over Explanation

- State facts, not rationale
- Avoid "why" - save that for Explanation docs
- Cut unnecessary words

**Do:**
```markdown
Returns the user's display name.

避免：

This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.

使用便于浏览的表格，而非散文

推荐：

| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |

避免：

The first parameter is `userId`, which should be a string containing
the unique user identifier. The second parameter is `options`, which
is an Options object containing the configuration.

各条目格式保持一致

类似项目的所有参考页面都应遵循相同的结构：

• 标题顺序相同
• 表格列相同
• 代码示例格式相同
• 相关链接部分相同

每个示例都必须可运行

• 包含所有导入语句
• 展示完整、可运行的代码
• 使用符合实际的值（而非“foo”“bar”“test123”）
• 有帮助时，包含预期输出

代码示例模式

首先展示常见用法

## Example

### Basic Usage

```typescript
const user = await getUser('user-123');
console.log(user.name);

带选项的用法

const user = await getUser('user-123', {
  includeMetadata: true,
  fields: ['name', 'email', 'role']
});

### Include Setup and Context

```markdown
```typescript
import { Client } from '@example/sdk';

// Initialize client (required once per application)
const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function
const result = await client.users.list();

### Use Realistic Values

**Do:** `userId: 'usr_a1b2c3d4'`
**Avoid:** `userId: 'foo'`

**Do:** `email: '[email protected]'`
**Avoid:** `email: '[email protected]'`

## Parameter Documentation Patterns

### Required vs Optional

Clearly indicate which parameters are required:

```markdown
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your API key |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retries` | `number` | No | `3` | Number of retry attempts |

复杂类型

对于对象参数，请说明其结构：

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `options` | `UserOptions` | No | Configuration options |

### UserOptions

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `includeDeleted` | `boolean` | No | Include soft-deleted users |
| `fields` | `string[]` | No | Fields to return |
| `limit` | `number` | No | Maximum results (default: 100) |

枚举值

清楚说明允许的值：

| Name | Type | Values | Description |
|------|------|--------|-------------|
| `status` | `string` | `active`, `pending`, `suspended` | User account status |

返回值文档

简单返回值

## Returns

`User` - The requested user object, or `null` if not found.

复杂返回值

## Returns

| Property | Type | Description |
|----------|------|-------------|
| `data` | `User[]` | Array of user objects |
| `pagination` | `Pagination` | Pagination metadata |
| `total` | `number` | Total matching records |

错误条件

## Errors

| Error | Condition |
|-------|-----------|
| `NotFoundError` | User does not exist |
| `UnauthorizedError` | Invalid or expired API key |
| `RateLimitError` | Too many requests |

API 参考文档要点

HTTP 端点

## Endpoint

```http
GET /api/v1/users/{userId}

路径参数

名称	类型	说明
userId	string	用户的唯一标识符

查询参数

名称	类型	必填	说明
fields	string	否	以逗号分隔的字段列表

标头

名称	必填	说明
Authorization	是	Bearer 令牌
X-Request-ID	否	请求跟踪 ID

响应

{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",
  "email": "[email protected]"
}

## Component/Props Reference

For UI components:

```markdown
## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary'` | `'primary'` | Visual style |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
| `disabled` | `boolean` | `false` | Disable interactions |
| `onClick` | `() => void` | - | Click handler |

## Slots

| Name | Description |
|------|-------------|
| `default` | Button content |
| `icon` | Icon to display before text |

相关链接部分

始终包含指向相关内容的链接：

## Related

- [createUser](/reference/create-user) - Create a new user
- [updateUser](/reference/update-user) - Modify user properties
- [deleteUser](/reference/delete-user) - Remove a user
- [User Authentication Guide](/guides/authentication) - How authentication works

检查关卡（按完成顺序）

将参考页面视为完成之前，请按顺序执行以下工作流。完成第 n 步后再进行第 n+1 步；每一步都有一项 通过 标准，可仅根据页面内容进行检查（无需“内部验证”）。

1. 结构 — 各部分符合项目模板（通常包括 Parameters、Returns、Example、Related；HTTP 文档还应包括 Endpoint、Path/Query、Headers、Response）。通过： 所有必需部分均已存在，或者在 Related 下有一行省略说明（例如“没有查询参数”）。
2. 表格 — 参数、返回值和错误使用表格，列与 各条目格式保持一致 和 必填与可选 的要求一致。通过： Description 单元格均不为空；已发布的 API 中没有 TBD / ???。
3. 可运行示例 — 至少有一个示例符合 每个示例都必须可运行 和 使用符合实际的值。通过： 已包含导入语句；用户可见的字符串符合实际（不是通用的 foo / bar，除非 API 仅用于示例说明）。
4. 相关内容 — 通过： ## Related 至少包含一个指向其他参考文档或指南的 Markdown 链接，或者明确说明没有相关符号。

参考页面检查清单

完成上方的 门槛（完成顺序） 后，请确认：

• 标题与符号/API 名称完全一致
• 描述是一个清晰的句子
• 记录了所有参数及其类型
• 明确标注必填项与可选项
• 指定可选参数的默认值
• 记录返回类型和结构
• 至少有一个完整、可运行的示例
• 示例使用符合实际的值
• 链接到相关页面
• 格式与文档中的其他参考页面一致

何时使用参考文档与其他文档类型

用户的想法	文档类型	示例
“我想学习”	教程	“构建你的第一个集成”
“我想做 X”	操作指南	“如何配置 SSO”
“我想了解”	说明文档	“我们的缓存如何工作”
“我需要查找 Y”	参考文档	“API 端点参考”

参考文档和说明文档是两种以认知为导向的类型，很容易混淆：参考文档会陈述中立事实，供你工作时查阅；说明文档则会探讨背后的原理，供你阅读和思考。完整的指南流程和区别请参阅 docs-style/references/diataxis-compass.md。

相关技能

• docs-style：核心写作规范和组件
• Diataxis 指南：类型选择、2×2 图表和质量模型
• tutorial-docs：面向学习内容的教程模式
• howto-docs：面向任务内容的操作指南模式
• explanation-docs：概念类文档模式