API 文档模板

本文档是 API 文档的标准模板，为所有 API 文档提供详细的结构模板、AI 提示词和质量检查点。

继承关系

L1 通用文档规范
  ↓
L2 API 文档规范
  ↓
L3 api-template.md（本文档）

扩展内容:

3 个新增规范：类型定义详细度、错误处理说明、性能考虑提示
4 个质量检查点：类型准确性、边界情况覆盖、示例完整性、中文表达
优化的 AI 提示词结构

文档结构模板

每个 API 函数的文档页面必须遵循以下 Markdown 结构：

markdown

---
title: [函数名]
description: "[函数名] - Dora Pocket 中 @esdora/[package] 库提供的[内容类别]工具函数，用于[功能描述]。"
---

# [函数名]

[一句话功能描述，说明核心用途和价值]

## 示例

### 基本用法

[最简单的使用示例，展示核心功能]

### [高级场景 1]

[展示特定使用场景]

### [高级场景 2]

[展示另一使用场景]

## 签名与说明

### 类型签名

\```typescript
function [functionName]<[Generics]>(
[param1]: [Type1],
[param2]: [Type2]
): [ReturnType]
\```

### 参数说明

| 参数     | 类型    | 描述       | 必需  |
| -------- | ------- | ---------- | ----- |
| [param1] | [Type1] | [详细说明] | 是/否 |
| [param2] | [Type2] | [详细说明] | 是/否 |

### 返回值

- **类型**: `[ReturnType]`
- **说明**: [返回值的详细说明]
- **特殊情况**: [错误时返回什么，边界情况的返回值]

### 泛型约束（如适用）

- **`[T]`**: [泛型参数的约束和用途说明]
- **`[K extends keyof T]`**: [泛型约束的含义]

## 注意事项与边界情况

### 输入边界

- [特殊输入处理说明 1]
- [特殊输入处理说明 2]

### 错误处理

- **异常类型**: [可能抛出的异常类型，如 TypeError, RangeError]
- **处理建议**: [如何捕获和处理异常，是否返回默认值]

### 性能考虑

- **时间复杂度**: O([complexity]) - [复杂度说明]
- **空间复杂度**: O([complexity]) - [内存使用说明]
- **优化建议**: [大数据量时的使用建议，性能敏感场景的注意事项]

## 相关链接

- [源码](https://github.com/esdora-js/esdora/blob/main/packages/[package]/src/[category]/[function-name]/index.ts)

AI 生成提示词（推荐模型：Codex）

模型推荐

根据 AI 模型调度策略：

推荐模型: Codex (gpt-5.1-codex)
- 优势：精确的类型签名生成、参数表格自动化、测试用例理解深入
- 适用场景：单函数 API 文档、类型复杂度高的函数
备选模型: Gemini (gemini-2.5-pro)
- 适用场景：涉及复杂跨模块依赖、需要深度架构理解的 API

完整提示词

text

# 上下文与角色 (Context & Role)

你是一位经验丰富的开源项目维护者和技术文档专家。你正在为一个名为 "Dora Pocket" 的项目撰写 API 参考文档。具体来说，是为其下的工具函数库编写内容。你的写作风格应该清晰、专业，并始终以开发者体验为中心。

你必须严格遵循文档规范体系的三层继承关系：
- **Layer 1 (L1)**: 通用文档规范 - Frontmatter、标题结构、语言、链接格式、代码示例、注意事项
- **Layer 2 (L2)**: API 文档规范 - 签名与说明章节、参数表格格式、示例优先原则
- **Layer 3 (L3)**: 本模板的增强规范 - 类型定义详细度、错误处理说明、性能考虑提示

# 任务 (Task)

你的任务是为我提供的一个函数，生成一份完整、准确、专业的 Markdown 格式的 API 文档页面。

# 输入 (Input)

我将为你提供两部分核心信息：
1. **函数源码**: 包含完整的函数实现和 JSDoc 注释（如有）
2. **单元测试代码**: 包含针对该函数的、使用 Vitest 编写的全面测试用例

# 输出格式 (Markdown 模板)

请严格按照以下 Markdown 模板生成文档：

---
title: [函数名]
description: "[函数名] - Dora Pocket 中 @esdora/[package] 库提供的[内容类别]工具函数，用于[功能描述]。"
---

# [函数名]

[一句话功能描述]

## 示例

### 基本用法

\```typescript
import { [functionName] } from '@esdora/[package]'

[基本使用代码]
[functionName]([args]) // => [结果]
\```

### [场景 2]

\```typescript
[高级使用示例]
\```

## 签名与说明

### 类型签名

\```typescript
[完整的 TypeScript 函数签名，包含泛型]
\```

### 参数说明

| 参数 | 类型 | 描述 | 必需 |
|------|------|------|------|
| [param1] | [Type1] | [详细说明，来自 JSDoc 或测试] | 是/否 |

### 返回值

- **类型**: `[ReturnType]`
- **说明**: [返回值详细说明]
- **特殊情况**: [错误时的返回值]

### 泛型约束（如适用）

- **`[T]`**: [泛型说明]

## 注意事项与边界情况

### 输入边界

[从测试用例中提取的边界情况]

### 错误处理

- **异常类型**: [函数可能抛出的异常类型]
- **处理建议**: [如何处理异常，是否需要 try-catch]

### 性能考虑

- **时间复杂度**: O([complexity])
- **空间复杂度**: O([complexity])
- **优化建议**: [性能敏感场景的使用建议]

## 相关链接

- [源码](https://github.com/esdora-js/esdora/blob/main/packages/[package]/src/[category]/[function-name]/index.ts)

# 核心指令与规范

## 1. 综合分析 (源码 + 测试用例)

- **必须结合源码和测试用例**：不能仅依赖源码或仅依赖测试，两者缺一不可
- **从测试用例中提取**：
  - 所有使用场景和示例代码
  - 边界情况和异常处理（null、undefined、空数组、负数等）
  - 函数的实际行为和预期输出
- **从源码中提取**：
  - 完整的 TypeScript 类型签名（包含泛型、联合类型、条件类型）
  - JSDoc 注释中的参数说明和返回值说明
  - 算法复杂度（循环、递归）

## 2. 示例格式 (严格遵循)

- **输出注释格式**：所有示例代码的输出必须使用 `// =>` 行内注释展示结果
  ```typescript
  isCircular(obj) // => true
  clamp(5, 0, 10) // => 5
  ```
- **完整性**：每个示例必须包含 `import` 语句，确保可独立运行
- **场景分类**：按照"基本用法 → 高级场景"的顺序组织示例
- **测试驱动**：优先使用测试用例中的代码作为示例

## 3. 签名与说明 (增强规范)

### 3.1 类型签名

- **完整性**：必须包含完整的 TypeScript 类型定义，包括泛型、约束、联合类型
- **来源**：直接从源码中复制函数签名，不要简化或改写
- **格式**：使用 TypeScript 代码块，保持原有的换行和缩进

### 3.2 参数说明

- **表格格式**：必须使用 Markdown 表格，列为：参数、类型、描述、必需
- **详细说明**：
  - 参数名：与源码保持一致
  - 类型：完整的 TypeScript 类型（如 `T[]`、`Record<string, any>`）
  - 描述：从 JSDoc 提取，补充测试用例中体现的行为
  - 必需：明确标注"是"或"否"（可选参数）

### 3.3 返回值

- **三要素**：类型、说明、特殊情况
- **特殊情况**：必须说明错误时返回什么（undefined、null、抛出异常）

### 3.4 泛型约束（新增）

- **适用条件**：函数签名包含泛型参数（如 `<T>`、`<K extends keyof T>`）
- **说明内容**：
  - 泛型参数的名称和约束条件
  - 泛型的用途和作用（如类型推断、类型安全）
  - 泛型参数之间的关系（如 `K extends keyof T` 表示 K 是 T 的键）

## 4. 注意事项与边界情况 (必须完整)

### 4.1 输入边界

- **来源**：必须从测试用例中总结
- **内容**：特殊输入的处理（null、undefined、空值、负数、超大数值等）

### 4.2 错误处理（新增）

- **异常类型**：
  - 明确函数可能抛出的异常类型（TypeError、RangeError、Error）
  - 从源码的 `throw` 语句或测试用例的 `expect().toThrow()` 中提取
- **处理建议**：
  - 是否需要 try-catch 包裹
  - 是否返回默认值（如 undefined）
  - 推荐的错误处理模式

### 4.3 性能考虑（新增）

- **时间复杂度**：
  - 分析源码中的循环、递归、嵌套结构
  - 标注 Big-O 复杂度（O(1)、O(n)、O(n²)、O(log n)）
  - 说明复杂度的含义（如 O(n) 表示与输入大小线性相关）
- **空间复杂度**：
  - 分析是否创建新数组、对象或递归调用栈
  - 标注额外内存使用（O(1) 原地操作、O(n) 创建新数组）
- **优化建议**：
  - 大数据量时的使用注意事项
  - 性能敏感场景的替代方案
  - 是否适合高频调用

## 5. 相关链接 (固定格式)

- **必须包含源码链接**：每个 API 文档必须在结尾包含"相关链接"章节
- **格式**：`- [源码](https://github.com/esdora-js/esdora/blob/main/packages/[package]/src/[category]/[function-name]/index.ts)`
- **路径规则**：
  - `[package]`: 如 `kit`、`color`、`date`
  - `[category]`: 如 `is`、`function`、`tree`、`url`
  - `[function-name]`: 与函数名一致的目录名（kebab-case）
- **示例**：
  ```markdown
  ## 相关链接

  - [源码](https://github.com/esdora-js/esdora/blob/main/packages/kit/src/is/is-circular/index.ts)
  ```
- **注意**：仅包含源码链接，不要添加其他链接（如测试文件、相关函数）

## 6. 禁止元描述 (Meta-Description Ban)

**严格禁止添加任何关于文档来源、生成过程的元描述**

### 6.1 禁止的元描述模式

- ❌ "以下示例全部来源于..."
- ❌ "以下类型信息来自构建流程生成的声明文件..."
- ❌ "本文档基于 XXX 版本生成..."
- ❌ "见 XXX 文件..."
- ❌ 任何形式的来源说明、生成过程说明

### 6.2 正确做法

- ✅ 直接开始章节内容，无需说明数据来源
- ✅ 示例章节直接展示 `### 基本用法`
- ✅ 签名章节直接展示 `\```typescript`
- ✅ 源码链接必须使用 Markdown 超链接格式：`[源码](URL)`，不使用行内代码

### 6.3 原则

**文档必须是官方的、规范的、自包含的内容**，不应包含任何关于文档生成过程的描述。用户阅读文档时应感受到这是官方发布的正式文档，而非自动生成的草稿。

## 7. 语言与表达 (中文规范)

- **主语言**：简体中文
- **专业术语**：参考 [术语表](./glossary.md)
- **代码注释**：可使用英文，但输出说明使用中文 `// => 结果`
- **表达风格**：
  - 清晰简洁，避免冗长
  - 使用主动语态："该函数用于..." 而非 "可以用来..."
  - 使用准确的技术术语，避免口语化表达

# 质量检查点（4 个关键验证）

生成文档后，必须进行以下 4 个质量检查：

## 检查点 1: 类型准确性检查

- [ ] 函数签名与源码完全一致（包括泛型、约束、可选参数）
- [ ] 参数表格中的类型与签名一致
- [ ] 返回值类型准确（包括联合类型、条件类型）
- [ ] 泛型约束的说明准确且完整

**验证方法**：将文档中的类型签名复制到 TypeScript 文件，确保能通过类型检查。

## 检查点 2: 边界情况覆盖检查

- [ ] 所有测试用例中的边界情况都已记录（null、undefined、空值、边界数值）
- [ ] 错误处理部分包含所有可能的异常类型
- [ ] 输入边界部分完整且准确
- [ ] 特殊情况的返回值已明确说明

**验证方法**：对比测试文件中的 `expect` 断言，确保所有边界情况都在"注意事项"章节中体现。

## 检查点 3: 示例完整性检查

- [ ] 基本用法示例存在且可运行（包含 import 语句）
- [ ] 所有示例使用 `// =>` 注释展示输出
- [ ] 高级场景覆盖主要使用场景（至少 2-3 个）
- [ ] 示例代码与测试用例一致或源于测试用例

**验证方法**：复制示例代码到 TypeScript 项目，确保能成功运行且输出与注释一致。

## 检查点 4: 中文表达规范检查

- [ ] 所有技术术语使用简体中文且符合术语表
- [ ] 描述清晰简洁，无语法错误
- [ ] 代码注释使用中文说明（如 `// => 返回 true`）
- [ ] 避免直译英文的生硬表达
- [ ] **无任何元描述**：无来源说明（"以下示例来源于..."）、生成过程说明（"以下类型信息来自..."）
- [ ] **源码链接使用超链接格式**：`[源码](https://github.com/...)`，不使用行内代码格式

**验证方法**：通读全文，确保表达自然流畅，符合中文技术文档习惯，且无任何元描述和格式错误。

# 输出要求总结

1. **结构完整**：必须包含所有 4 个主要章节（示例、签名与说明、注意事项、相关链接）
2. **内容准确**：基于源码和测试用例，不得臆造或简化
3. **格式规范**：严格遵循 Markdown 模板，代码块标注语言，表格格式正确
4. **质量保证**：通过 4 个质量检查点的验证
5. **继承规范**：符合 L1 通用规范 + L2 API 规范 + L3 增强规范

请开始生成文档。

使用示例：完整的 API 文档生成流程

1. 准备输入材料

函数源码文件：packages/kit/src/is/is-circular/index.ts
单元测试文件：packages/kit/tests/is/is-circular.test.ts

2. 使用 Codex 生成文档（推荐）

bash

# 使用完整的标准提示词模板（第一次生成）
codex -C packages/kit --full-auto exec "
PURPOSE: 为 isCircular 函数生成增强版 API 文档
TASK:
• 读取源码和测试文件
• 提取类型签名、参数说明、返回值、泛型约束
• 生成示例代码（基本用法 + 高级场景）
• 添加错误处理说明和性能考虑
• 执行 4 个质量检查点验证
MODE: auto
CONTEXT: @src/is/is-circular/**/* @tests/is/is-circular.test.ts @../../docs/contributing/documentation/api-template.md
EXPECTED: 完整的 API 文档，符合 api-template.md 规范，包含类型定义、错误处理、性能说明，通过 4 个质量检查点
RULES: \$(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | 遵循 L1+L2+L3 规范，使用 api-template.md 提示词 | auto=FULL operations
" --skip-git-repo-check -s danger-full-access

# 后续生成（使用会话恢复）
codex --full-auto exec "为 is-empty 函数生成类似的增强版 API 文档" resume --last --skip-git-repo-check -s danger-full-access

3. 使用 Gemini 生成文档（备选，复杂依赖场景）

bash

cd packages/kit && gemini -p "
PURPOSE: 为涉及复杂跨模块依赖的 API 生成增强版文档
TASK:
• 分析函数的跨模块依赖关系
• 提取类型签名和泛型约束
• 生成完整的示例代码和边界情况说明
• 添加性能考虑和优化建议
MODE: write
CONTEXT: @src/**/* @tests/**/* @../../docs/contributing/documentation/api-template.md | Memory: 遵循 api-template.md 增强规范，包含类型定义、错误处理、性能说明
EXPECTED: 符合 api-template.md 规范的 API 文档，通过 4 个质量检查点
RULES: \$(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | 遵循 L1+L2+L3 规范 | write=CREATE/MODIFY/DELETE
" --approval-mode yolo

4. 质量验证

生成文档后，执行以下验证：

bash

# 检查点 1: 类型准确性
# 将签名复制到 TypeScript 文件，运行 tsc 检查

# 检查点 2: 边界情况覆盖
rg "expect\(" tests/is/is-circular.test.ts -A 1 | grep -E "null|undefined|empty|边界"

# 检查点 3: 示例完整性
# 复制示例代码到临时文件，运行确保输出正确

# 检查点 4: 中文表达
# 通读文档，检查术语一致性和表达流畅性

版本历史

v1.0 (2025-11-19): 初始版本，建立 API 文档标准模板，增加 3 个新规范和 4 个质量检查点

API 文档模板 ​

继承关系 ​

文档结构模板 ​

AI 生成提示词（推荐模型：Codex） ​

模型推荐 ​

完整提示词 ​

使用示例：完整的 API 文档生成流程 ​

1. 准备输入材料 ​

2. 使用 Codex 生成文档（推荐） ​

3. 使用 Gemini 生成文档（备选，复杂依赖场景） ​

4. 质量验证 ​

相关文档 ​

版本历史 ​

API 文档模板

继承关系

文档结构模板

AI 生成提示词（推荐模型：Codex）

模型推荐

完整提示词

使用示例：完整的 API 文档生成流程

1. 准备输入材料

2. 使用 Codex 生成文档（推荐）

3. 使用 Gemini 生成文档（备选，复杂依赖场景）

4. 质量验证

相关文档

版本历史