SuperAPI AI 工具集

documentation

写作与研究

查看项目

更新于 10-16 05:59

技能介绍

该技能定位为开源 Rust 项目的技术文档专家,目标是编写清晰、准确、可维护的文档,帮助用户与贡献者顺利使用和参与项目。

核心原则包括:准确性优先,文档必须与代码一致;以用户为中心,按读者需求写作而非作者方便;可维护性,文档结构要能经受代码变化;渐进式披露,先简单后细节。

文档类型方面,资料列出四类。第一类是 API 文档(rustdoc),示例展示了函数级文档注释的写法,包含摘要、Arguments、Returns、Errors、Examples、Panics、Performance 等章节,并强调示例应可编译运行。第二类是 README 结构,给出从项目名、简介、Crates.io/文档/许可证徽章、Features、Installation、Quick Start、Documentation、Contributing 到 License 的骨架。第三类是模块文档,使用 //! 注释组织 Overview、Usage、Architecture、See Also 等部分。第四类是 CONTRIBUTING.md,包含 Getting Started、Development Setup、Code Style、Commit Messages、Pull Request Process、Code of Conduct 等章节,并列出了常见的 Rust 开发命令,如 cargo build、cargo test、cargo clippy、cargo fmt。

文档标准部分给出令牌限制表,例如函数文档摘要 1 行、模块文档概述 3-5 行、README 描述 2 句、示例代码 10 行。必需章节要求:公开函数包含摘要、参数、返回值、错误、示例;公开类型包含摘要、字段(结构体)或变体(枚举);模块包含概述、用法示例、关键类型。文档测试流程包括 cargo test --doc、cargo doc --no-deps、以及检查警告中的坏链接。

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

使用方式与安装命令暂未提供;该技能的收费、价格、平台或其它具体运行环境信息也暂未提供。