documenting-rust-code

此技能为 HASH 存储库中的 Rust 代码编写提供了一套全面的文档规范。它通过建立关于文档注释、函数说明、类型规格和模块级文档的清晰标准，确保遵循 rustdoc 的规范。此技能旨在为从事 HASH 代码库开发的工程师提供指导，确保所有公开 API 都能正确标注，并透过内部文档链接 (intra-doc links) 保持易维护性与可发现性，效仿 serde、time 和 jiff 等高性能 crate 的社区标准。

• 标准化文档注释的结构，要求以简洁的单行摘要作为开头，随后进行详细说明。

• 强制要求所有类型参考使用内部文档链接，以提升 IDE 导航与文档网站的可用性。

• 定义错误文档的强制格式，要求所有可能失败的函数必须包含显式的 # Errors 章节。

• 鼓励为公开 API 加入实用的示例，并确保这些示例有效且可透过 cargo doc 验证。

• 不建议对 Debug、Display 或 From 等标准 trait 实现编写冗余说明，并禁止使用独立的 # Returns 章节，改采用行内描述方式。

• 当您在 HASH 项目中为新的 Rust 模块、函数、结构或 trait 编写文档时，请使用此技能。

• 针对 0-2 个参数的简单函数与需要 # Arguments 章节的复杂函数，请遵循指定的编写模式。

• 请务必链接如 Vec 或 HashMap 等标准库类型，以确保清晰度并符合标准规范的交叉引用。

• 在提交变更之前，请透过执行 cargo doc --no-deps --all-features 在本地验证文档的准确性与格式。

• 请将文档注释与代码行分开，以确保可读性并遵守标准 Rust 风格指南。