SuperAPI AI 工具集

documentation

写作与研究

查看项目

更新于 10-16 04:05

技能介绍

用途

本技能是面向开源 Rust 项目的技术文档专家,目标是编写清晰、准确、可维护的文档,帮助用户和贡献者顺利使用与参与项目。核心原则包括:准确性优先(文档必须与代码一致)、以用户为中心(为读者需求而写,而非为写作者方便)、可维护(文档结构能经受代码变更)、渐进式披露(从简单开始,按需增加细节)。

主要能力

技能覆盖多种文档类型:

  1. API 文档(rustdoc):为公开函数编写文档注释,包含摘要、Arguments、Returns、Errors、Examples、Panics、Performance 等章节,示例代码需可编译运行。
  2. README 结构:包含项目名、1-2 句简介、Crates.io/Documentation/License 徽章、Features、Installation(Cargo.toml 依赖)、Quick Start 示例、Documentation 链接、Contributing、License。
  3. 模块文档:使用 //! 注释,包含 Overview、Usage 示例、Architecture、See Also 交叉引用。
  4. CONTRIBUTING.md:包含 Getting Started(fork、clone、branch)、Development Setup(安装 Rust、cargo build/test/clippy)、Code Style、Commit Messages(约定式提交)、Pull Request Process、Code of Conduct。

使用方式

技能提供文档模板与写作规范,并给出文档测试命令:

# 测试文档示例
cargo test --doc

# 生成并检查文档
cargo doc --no-deps

# 检查断链
cargo doc --no-deps 2>&1 | grep "warning"

文档标准包含 Token 限制(函数摘要 1 行、模块概览 3-5 行、README 描述 2 句、示例代码 10 行)与必需章节(公开函数:Summary、Arguments、Returns、Errors、Examples;公开类型:Summary、Fields/Variants;模块:Overview、Usage example、Key types)。

适用场景

适用于 Rust 开源项目的文档编写与维护,包括 API 参考、README、模块说明、贡献指南。可选集成 ZDP(Zestic AI Development Process)生命周期,产出发布说明、无障碍报告、事件运行手册、活文档等,并与 /acceptance-testing、/responsible-ai、/mlops-monitoring 等技能协调。

限制

约束包括:无代码验证不写文档、示例必须可编译运行、文档需与代码变更同步、不记录内部实现细节、避免营销语言。成功指标为:所有公开项均有文档、文档示例可编译、README 支持快速上手、贡献者可独立入门。