documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation

文档编写

Follow writing-voice for tone.

Documentation explains why, not what. Users can read code to see what it does. They need you to explain the reasoning.

语气请遵循写作风格。

文档要解释原因，而非内容。用户可以通过阅读代码了解功能，他们需要你解释设计思路。

Folder READMEs

文件夹README

Primary job: explain why this folder exists and the mental model.

核心作用：解释该文件夹存在的原因以及对应的思维模型。

Can Include

可包含内容

ASCII art diagrams for complex relationships
Overview of key exports or entry points
Brief file descriptions IF they add context beyond the filename
Relationships to other folders

用于展示复杂关系的ASCII艺术图
关键导出内容或入口点概述
若能提供文件名之外的上下文，可添加简短的文件说明
与其他文件夹的关联关系

Avoid

需避免内容

Exhaustive file listings that just duplicate
```
ls
```
Descriptions that repeat the filename ("auth.ts - authentication")
Implementation details better expressed in code

详尽的文件列表，这只是重复
```
ls
```
命令的结果
重复文件名的描述（如“auth.ts - 认证”）
更适合在代码中体现的实现细节

Good

优秀示例

markdown

undefined

markdown

undefined

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.

undefined

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

┌─────────────┐     ┌──────────────┐
│ Field Schema│────▶│  to-arktype  │────▶ 运行时验证
└─────────────┘     ├──────────────┤
                    │  to-drizzle  │────▶ SQLite 列
                    └──────────────┘

字段 schema 是带有

x-component

提示的纯JSON Schema对象。每个转换器接收相同的输入，为特定的使用方生成输出。

undefined

Bad

反面示例

markdown

undefined

markdown

undefined

Converters

转换器

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


The bad example just lists files without explaining the pattern or when to add new converters.

```
to-arktype.ts
```
- 转换为ArkType格式
```
to-drizzle.ts
```
- 转换为Drizzle格式
```
index.ts
```
- 导出内容


反面示例仅罗列文件，未解释设计模式或添加新转换器的场景。

JSDoc Comments

JSDoc注释

JSDoc explains when and why to use something, not just what it does.

JSDoc要解释何时及为何使用某功能，而非仅说明功能是什么。

Good

优秀示例

typescript

/**
 * 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() { ... }

typescript

/**
 * 获取所有表助手的数组。
 *
 * 适用于需要遍历所有表的提供者和索引场景。
 * 仅返回表助手，排除`clearAll`等工具方法。
 *
 * @example
 * ```typescript
 * for (const table of tables.defined()) {
 *   console.log(table.name, table.count());
 * }
 * ```
 */
defined() { ... }

Bad

反面示例

typescript

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

typescript

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

Rules

规则

Include
```
@example
```
blocks with realistic usage
Explain WHEN to use it, not just WHAT it does
Document non-obvious behavior or edge cases
Public APIs get detailed docs; internal helpers can be minimal

包含
```
@example
```
代码块，展示真实使用场景
解释何时使用，而非仅说明功能
记录非直观的行为或边缘情况
公开API需要详细文档；内部辅助方法可简化处理

Code Comments

代码注释

Comments explain why, not what.

注释要解释原因，而非内容。

Good

优秀示例

typescript

// 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);

typescript

// Y.Doc的clientID是随机32位整数，因此无法依赖其排序。
// 使用条目自身的时间戳实现确定性排序。
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

Bad

反面示例

typescript

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

typescript

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

Rules

规则

If the code is clear, don't comment it
Comment the "why" when it's not obvious
Comment workarounds with links to issues/docs
Delete commented-out code; that's what git is for

若代码逻辑清晰，无需添加注释
当逻辑不直观时，注释说明原因
对临时解决方案添加注释，并附上问题/文档链接
删除被注释掉的代码；这类内容可通过git查看历史版本