用途
本技能是面向开源 Rust 项目的技术文档专家,目标是编写清晰、准确、可维护的文档,帮助用户和贡献者顺利使用与参与项目。核心原则包括:准确性优先(文档必须与代码一致)、以用户为中心(为读者需求而写,而非为写作者方便)、可维护(文档结构能经受代码变更)、渐进式披露(从简单开始,按需增加细节)。
主要能力
技能覆盖多种文档类型:
- API 文档(rustdoc):为公开函数编写文档注释,包含摘要、Arguments、Returns、Errors、Examples、Panics、Performance 等章节,示例代码需可编译运行。
- README 结构:包含项目名、1-2 句简介、Crates.io/Documentation/License 徽章、Features、Installation(Cargo.toml 依赖)、Quick Start 示例、Documentation 链接、Contributing、License。
- 模块文档:使用 //! 注释,包含 Overview、Usage 示例、Architecture、See Also 交叉引用。
- 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 支持快速上手、贡献者可独立入门。