⚡

文档化技能Skill documentation

文档化技能用于自动从代码生成和更新软件文档，包括项目概述、安装说明、API端点描述、变更日志等，旨在维护准确和有用的文档，提高开发效率和团队协作。关键词：文档生成、代码文档化、API文档、变更日志、软件开发文档、SEO优化。

DevOps 0 次安装 0 次浏览 更新于 3/20/2026

name: 文档化 description: 从代码生成和更新文档。在成功实施后使用。

文档化技能

目的

维护准确、有帮助的文档。

模板

README 模板

参考: templates/readme-template.md

API 文档模板

参考: templates/api-doc-template.md

变更日志模板

参考: templates/changelog-template.md

JSDoc 标准

/**
 * 函数功能的简要描述。
 *
 * @param {string} name - 描述 name 参数
 * @param {Options} options - 描述 options
 * @returns {Result} 描述返回值
 * @throws {ValidationError} 当验证失败时
 * @example
 * const result = myFunction('test', { flag: true });
 */
function myFunction(name: string, options: Options): Result {
  // ...
}

文档类型

README

  • 项目概述
  • 安装说明
  • 快速入门指南
  • 配置选项
  • 贡献指南

API 文档

  • 端点描述
  • HTTP 方法
  • 请求/响应格式
  • 认证要求
  • 错误代码

代码文档

  • JSDoc/docstrings
  • 内联注释（为什么，而不是什么）
  • 类型注解
  • 示例用法

变更日志

  • 版本历史
  • 重大更改
  • 迁移步骤
  • 弃用通知

文档检查清单

  • [ ] README 最新
  • [ ] API 端点已文档化
  • [ ] 代码示例有效
  • [ ] 变更日志已更新
  • [ ] 公共 API 上有 JSDoc
  • [ ] 链接有效
  • [ ] 拼写/语法正确

文档生成

运行: scripts/generate-docs.py

最佳实践

做

  • 保持示例最新
  • 文档化重大更改
  • 使用一致的格式
  • 包含常见用例
  • 解释“为什么”而不仅仅是“如何”

不做

  • 文档化实现细节
  • 让示例过时
  • 跳过错误场景
  • 使用行话而不解释
  • 假设读者知识

存储位置

保存报告到: docs/reviews/documentation-{session}.md