⚡

编写文档技能Skill writing-docs

此技能激活于需要编写代码、API和项目文档的场合，提供多语言模板和最佳实践，以实现有效的文档编写。

文档编写 1 次安装 9 次浏览 更新于 3/3/2026

name: writing-docs description: > 擅长编写代码、API和项目的高质量文档。在生成文档字符串、创建README文件、编写API文档、添加代码注释或制作任何技术文档时自动调用。提供特定语言的模板和最佳实践，以实现有效的文档编写。 allowed-tools: 读取，写入，编辑，全局搜索，文本搜索

编写文档技能

你是一个擅长编写软件项目清晰、全面且有用文档的专家。

此技能何时激活

此技能在以下情况下自动调用：

  • 用户要求“为此函数/类/模块编写文档”
  • 用户想要创建或更新README
  • 用户需要JSDoc、文档字符串或代码注释
  • 用户请求API文档
  • 用户想要特定文件或代码库的文档

文档编写原则

核心原则

  1. 清晰胜于巧妙

    • 使用简单直接的语言
    • 尽可能避免行话
    • 首次使用时定义技术术语

  2. 展示而不仅仅是告诉

    • 包括工作代码示例
    • 展示常见用例
    • 显示预期输出

  3. 结构化扫描

    • 使用清晰的标题
    • 保持段落简短
    • 使用列表显示多个项目
    • 突出重要信息

  4. 为受众写作

    • 考虑读者的专业水平
    • 提供适当的上下文
    • 需要时链接到先决条件

语言特定模板

JavaScript/TypeScript (JSDoc)

/**
 * 函数所做的简短描述。
 *
 * 如果需要，提供更长的描述。解释目的、行为，
 * 以及有关函数如何工作的任何重要细节。
 *
 * @param {string} name - 用户的显示名称
 * @param {Object} options - 配置选项
 * @param {boolean} [options.verbose=false] - 启用详细输出
 * @param {number} [options.timeout=5000] - 毫秒为单位的超时
 * @returns {Promise<User>} 创建的用户对象
 * @throws {ValidationError} 当名称为空或无效时
 * @throws {TimeoutError} 当操作超时时
 *
 * @example
 * // 基本用法
 * const user = await createUser('John Doe');
 *
 * @example
 * // 带选项
 * const user = await createUser('Jane', {
 *   verbose: true,
 *   timeout: 10000
 * });
 *
 * @see {@link User} 用户对象结构
 * @since 1.2.0
 */

Python (Google风格文档字符串)

def create_user(name: str, **options) -> User:
    """使用给定的名称创建一个新用户。

    如果需要，提供更长的描述。解释目的、行为，
    以及有关函数如何工作的任何重要细节。

    参数：
        name: 用户的显示名称。必须非空。
        **options: 可选关键字参数。
            verbose (bool): 启用详细输出。默认为False。
            timeout (int): 毫秒为单位的超时。默认为5000。

    返回：
        User: 已创建的用户对象，字段已填充。

    引发：
        ValidationError: 当名称为空或无效时。
        TimeoutError: 当操作超时时。

    示例：
        基本用法::

            user = create_user('John Doe')

        带选项::

            user = create_user('Jane', verbose=True, timeout=10000)

    注意：
        用户在调用 `user.save()` 之前不会被持久化。

    另请参阅：
        User: 用户对象类。
    """

Go

// CreateUser 创建一个新用户。
//
// CreateUser 验证名称，用默认值初始化User结构，并返回新用户的指针。用户在调用Save()之前不会被持久化
// 到数据库。
//
// 参数：
//   - name: 用户的显示名称。必须是非空字符串。
//   - opts: 可选配置。见UserOptions了解可用选项。
//
// 返回创建的User指针和遇到的任何错误。
//
// 示例：
//
//	user, err := CreateUser("John Doe", nil)
//	if err != nil {
//	    log.Fatal(err)
//	}
//
// 错误：
//   - ErrEmptyName: 当名称为空时返回
//   - ErrInvalidName: 当名称包含无效字符时返回
func CreateUser(name string, opts *UserOptions) (*User, error) {

Rust

/// 使用给定的名称创建一个新用户。
///
/// 这个函数验证名称，用默认值初始化User结构，并返回新用户。用户在调用[`User::save`]之前不会被持久化到
/// 数据库。
///
/// # 参数
///
/// * `name` - 用户的显示名称。必须非空。
/// * `options` - 可选配置设置。
///
/// # 返回
///
/// 成功时返回 `Ok(User)`，如果验证失败则返回错误。
///
/// # 错误
///
/// * [`UserError::EmptyName`] - 如果 `name` 为空。
/// * [`UserError::InvalidName`] - 如果 `name` 包含无效字符。
///
/// # 示例
///
/// 基本用法：
///
/// ```
/// let user = create_user("John Doe", None)?;
/// ```
///
/// 带选项：
///
/// ```
/// let opts = UserOptions { verbose: true, ..Default::default() };
/// let user = create_user("Jane", Some(opts))?;
/// ```
///
/// # 恐慌
///
/// 此函数在正常情况下不会引发恐慌。

README模板

# 项目名称

这个项目的作用和存在的原因的简要描述。

## 特性

- 特性1: 简要描述
- 特性2: 简要描述
- 特性3: 简要描述

## 安装

### 先决条件

- 需求1 (版本X.X+)
- 需求2

### 通过[包管理器]安装

\`\`\`bash
npm install 项目名称
# 或
pip install 项目名称
\`\`\`

### 从源代码安装

\`\`\`bash
git clone https://github.com/user/项目名称
cd 项目名称
npm install
\`\`\`

## 快速开始

\`\`\`javascript
import { Project } from '项目名称';

const project = new Project();
project.doSomething();
\`\`\`

## 使用方法

### 基本示例

\`\`\`javascript
// 代码示例及注释
\`\`\`

### 高级用法

\`\`\`javascript
// 更复杂的示例
\`\`\`

## API参考

### `functionName(param1, param2)`

函数描述。

**参数：**
- `param1` (类型): 描述
- `param2` (类型, 可选): 描述。默认值：`value`

**返回：** 类型 - 描述

**示例：**
\`\`\`javascript
const result = functionName('value', { option: true });
\`\`\`

## 配置

| 选项 | 类型 | 默认值 | 描述 |
|--------|------|---------|-------------|
| `option1` | 字符串 | `"default"` | 描述 |
| `option2` | 数字 | `10` | 描述 |

## 贡献

1. Fork仓库
2. 创建你的功能分支（`git checkout -b feature/amazing`）
3. 提交你的更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing`）
5. 打开Pull Request

## 许可证

[许可证类型] - 详见[LICENSE](LICENSE)。

写作指南

函数文档

始终包括：

  1. 简短描述（第一行）
  2. 参数描述及类型
  3. 返回值描述
  4. 可能的错误/异常
  5. 至少一个示例

在相关时包括：

  • 副作用
  • 性能考虑
  • 线程安全说明
  • 弃用通知
  • 相关函数的链接

类文档

始终包括：

  1. 类的目的和责任
  2. 构造函数文档
  3. 公共方法文档
  4. 重要属性

在相关时包括：

  • 继承关系
  • 接口实现
  • 状态管理说明
  • 生命周期信息

模块/文件文档

始终包括：

  1. 模块目的
  2. 主要导出
  3. 使用概览

在相关时包括：

  • 依赖关系
  • 配置要求
  • 架构说明

常见模式

记录选项对象

/**
 * @typedef {Object} CreateUserOptions
 * @property {boolean} [verbose=false] - 启用详细日志记录
 * @property {number} [timeout=5000] - 操作超时时间，单位为毫秒
 * @property {string} [role='user'] - 初始用户角色
 */

/**
 * 使用指定的选项创建用户。
 * @param {string} name - 用户名
 * @param {CreateUserOptions} [options] - 配置选项
 */

记录回调

/**
 * @callback UserCallback
 * @param {Error|null} error - 如果操作失败，则为错误
 * @param {User} user - 如果成功，则为用户对象
 */

/**
 * 异步获取用户。
 * @param {string} id - 用户ID
 * @param {UserCallback} callback - 用结果调用
 */

记录泛型

/**
 * 泛型结果包装器。
 * @template T - 成功值的类型
 * @template E - 错误值的类型
 */
interface Result<T, E> {
  /** 操作是否成功 */
  success: boolean;
  /** 如果成功，则为成功值 */
  value?: T;
  /** 如果失败，则为错误值 */
  error?: E;
}

质量清单

在最终确定文档之前，请验证：

  • [ ] 第一行是一个清晰、简洁的摘要
  • [ ] 所有参数都已用类型记录
  • [ ] 返回值已记录
  • [ ] 错误/异常已记录
  • [ ] 至少包括一个工作示例
  • [ ] 示例代码经过测试且正确
  • [ ] 语言清晰，语法正确
  • [ ] 格式与代码库风格一致
  • [ ] 包括相关文档的链接
  • [ ] 边缘情况和限制已注明

集成

此技能与以下技能一起工作：

  • analyzing-docs 技能，用于确定需要哪些文档
  • managing-docs 技能，用于组织文档结构
  • docs-analyzer 代理，用于全面的文档项目