SuperAPI AI 工具集

documenting-rust-code

编程与开发

查看项目

更新于 10-16 05:50

技能介绍

用途:为 HASH 仓库中的 Rust 代码编写文档,遵循 rustdoc 约定与高质量标准(参考 time、jiff、serde)。

主要能力与规则:每个文档注释以单行摘要开头;所有类型引用使用 intra-doc 链接;用 # Errors 记录所有错误条件;为公开 API 提供实用示例;链接标准库类型如 [Vec]、[HashMap]。简单函数(0–2 个参数)用行内参数描述;在正文描述返回值,而非单独章节。不要为 Debug、Display、From 等标准 trait 实现写文档;不要新增单独的 # Returns 章节;不要重复签名中已有的变量类型;不要在代码同行写注释;不要遗漏可失败函数的错误文档。

文档模式:简单函数行内描述参数;复杂函数(3 个及以上参数)使用 # Arguments 章节,逐条列出参数。错误用 # Errors 列出各错误变体并给出链接定义。模块文档使用 //! ,列出主要类型并提供 # Examples。示例中可含错误处理,示例结尾可用 # Ok::<(), Box<dyn core::error::Error>>(()) 隐藏。

使用方式:按上述规则编写注释。验证命令:cargo doc --no-deps --all-features。

参考文件:references/function-documentation.md(函数与方法)、references/type-documentation.md(类型、结构体、枚举与 trait)、references/error-documentation.md(错误与 panic)、references/examples-and-links.md(示例与 intra-doc 链接)。

限制:该技能针对 HASH 代码库约定,其他项目需自行调整;资料未提供收费、价格、平台等信息。