SuperAPI AI 工具集

rust-documentation

写作与研究

查看项目

更新于 10-15 21:48

技能介绍

用途:为 Rust 项目设计、编写、构建、测试和发布文档,把文档视为可执行的公共接口。涵盖 rustdoc 注释、crate 与模块文档、doctest、文档内链接、README 生成、mdBook 长文档、docs.rs 配置、链接检查与拼写检查,以及文档发布前的质量门禁。范围不含:一般测试架构、公共 API 兼容性审查、Cargo 元数据与发布、API 形态与 trait 设计,这些应交给相应主题;本技能只负责记录已经存在的 API,而非决定 API 应该是什么。

主要能力:为每个公开项按需记录作用语义、示例、错误、panic、unsafe 安全性、取消、阻塞、分配、复杂度、平台、feature 与 MSRV;提倡使用 [Client::send] 这类文档内链接而非手写 URL;通过 #![deny(rustdoc::broken_intra_doc_links)] 在 crate 边界检查断链;按 Rust API Guidelines 的五条文档规则(C-DOC、C-DOC-COMMENT、C-META、C-EXAMPLE、C-LINK)作为验收标准,可对 C-DOC 使用 #![deny(missing_docs)]。

使用方式:区分 ///(记录下一项)与 //!(记录当前模块或 crate);crate 顶部 //! 需覆盖用途、入门、feature、MSRV 与许可证;用不同 fence 属性区分可运行、no_run、compile_fail 与 ignore 示例。常用命令:cargo test --workspace --doc --all-features;RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps;mdbook test 与 mdbook build 指定路径;lychee 和 typos 检查链接与拼写;cargo fmt --all --check。

适用场景:公开 crate 的 API 文档与 README、教程与迁移指南(mdBook)、带 doctest 的示例、docs.rs 版本化发布,以及文档发布前的质量门禁。

限制:本技能不收集、存储或传输用户数据;未经授权不得发布、修改托管文档或开启外部分析;只运行项目已有或获批准安装的工具;CI 中检查型任务不得静默改写正文;被跳过的外部、平台或托管验证需明确记录。