documentation

文档

语气请遵循 writing-voice。对于架构讲解、文件夹心智模型或面向新手的说明，请先说明归属、边界或流程；结合代码阐释模型，并在有帮助时指出常见误解。

文档解释为什么，而不是是什么。用户可以阅读代码，了解它的作用；他们需要你解释其中的理由。

文件夹 README

首要任务：说明这个文件夹为什么存在，以及应如何理解它。

开篇应给出有用的模型：这个文件夹负责什么、为什么存在，以及未来修改时应保留什么边界。

可以包含

• 用于说明复杂关系的 ASCII 图
• 关键导出项或入口的概述
• 简要的文件说明，前提是能提供超出文件名的信息
• 与其他文件夹的关系

避免

• 只是重复 ls 结果的详尽文件列表
• 重复文件名的描述（“auth.ts - 身份验证”）
• 更适合在代码中说明的实现细节

好的示例

# Converters

Transform field schemas into format-specific representations.

```
┌─────────────┐     ┌──────────────┐
│ Field Schema│────▶│  to-arktype  │────▶ Runtime validation
└─────────────┘     ├──────────────┤
                    │  to-drizzle  │────▶ SQLite columns
                    └──────────────┘
```

Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.

不好的示例

# Converters

- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports

不好的示例只是列出文件，没有解释其中的模式，也没有说明何时应添加新的转换器。

JSDoc 注释

JSDoc 解释何时以及为何使用某项功能，而不只是说明它的作用。

好的示例

/**
 * Get all table helpers as an array.
 *
 * Useful for providers and indexes that need to iterate over all tables.
 * Returns only the table helpers, excluding utility methods like `clearAll`.
 *
 * @example
 * ```typescript
 * for (const table of tables.defined()) {
 *   console.log(table.name, table.count());
 * }
 * ```
 */
defined() { ... }

不好的示例

/** Returns all table helpers as an array. */
defined() { ... }

规则

• 添加包含真实用法的 @example 代码块
• 解释何时使用，而不只是说明它的作用
• 记录不明显的行为或边缘情况
• 为公共 API 提供详细文档；内部辅助函数的说明可以简略

代码注释

注释解释为什么，而不是是什么。

好的示例

// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
// Use timestamps from the entries themselves for deterministic sorting.
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

不好的示例

// Sort the entries
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

规则

• 如果代码足够清晰，就不要添加注释
• 在原因不明显时，注释说明“为什么”
• 为变通方案添加注释，并附上问题或文档的链接
• 删除注释掉的代码；这正是 git 的用途