name: 文档编写 description: 代码内文档、文件夹README和代码注释。用于编写README.md文件、JSDoc注释或解释代码组织。

文档编写

遵循writing-voice的语气。

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

文件夹README

主要任务：解释为什么这个文件夹存在以及思维模型。

可以包括

复杂关系的ASCII艺术图表
关键导出或入口点的概述
简要文件描述（如果它们为文件名添加上下文）
与其他文件夹的关系

避免

仅重复ls的详尽文件列表
重复文件名的描述（“auth.ts - 身份验证”）
在代码中更好地表达的实现细节

好例子

# 转换器

将字段模式转换为特定格式的表示。

```
┌─────────────┐     ┌──────────────┐
│ 字段模式   │────▶│  to-arktype  │────▶ 运行时验证
└─────────────┘     ├──────────────┤
                    │  to-drizzle  │────▶ SQLite列
                    └──────────────┘
```

字段模式是纯JSON Schema对象，带有`x-component`提示。每个转换器采用相同的输入并为特定消费者产生输出。

坏例子

# 转换器

- `to-arktype.ts` - 转换为ArkType
- `to-drizzle.ts` - 转换为Drizzle
- `index.ts` - 导出

坏例子只是列出文件，而没有解释模式或何时添加新转换器。

JSDoc注释

JSDoc解释何时和为什么使用某物，而不仅仅是它做什么。

好例子

/**
 * 将所有表格助手作为数组获取。
 *
 * 对于需要遍历所有表格的提供程序和索引非常有用。
 * 仅返回表格助手，排除实用方法如`clearAll`。
 *
 * @example
 * ```typescript
 * for (const table of tables.defined()) {
 *   console.log(table.name, table.count());
 * }
 * ```
 */
defined() { ... }

坏例子

/** 返回所有表格助手作为数组。 */
defined() { ... }

规则

包含带有现实用法的@example块
解释何时使用它，而不仅仅是它做什么
记录不明显的行文或边缘情况
公共API获得详细文档；内部辅助函数可以是简短的

代码注释

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

好例子

// Y.Doc clientID是随机的32位整数，因此我们不能依赖顺序。
// 使用条目本身的时间戳进行确定性排序。
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

坏例子

// 对条目进行排序
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

规则

如果代码清晰，不要评论它
当不显而易见时，评论“为什么”
评论变通方法并链接到问题/文档
删除注释掉的代码；git就是为了这个的