名称: rust代码文档化描述: HASH代码库的Rust文档实践。用于编写文档注释、文档函数/类型/特性/模块、创建错误部分、使用内部文档链接或遵循rustdoc约定。许可证: AGPL-3.0 元数据: 触发器: 类型: 领域强制执行: 建议优先级: 高关键词: - rustdoc - 文档注释 - 文档 - 内部文档链接意图模式: - “\bdocument(ing|ation)?\b.?\b(rust|function|type|struct|enum|trait|module)\b" - "\b(write|add|create)\b.?\bdoc\scomment\b" - "\b#\s(Errors|Panics|Examples|Arguments)\b”

Rust文档实践

在HASH仓库中记录Rust代码的全面指南，遵循rustdoc约定。

核心原则

遵循高质量标准如time、jiff和serde:

✅ 做:

每个文档注释以单行摘要开始
对所有类型引用使用内部文档链接
用# Errors文档所有错误条件
为公共API包含实用示例
链接标准库类型: [Vec], [HashMap], 等。
对简单函数使用内联参数描述 (0-2 参数)
在主文本中描述返回值，而不是单独部分

❌ 不做:

文档标准特性实现 (Debug, Display, From)
添加单独的# Returns部分 (改为内联)
提及签名中已有的变量类型
使用与代码同行的注释
跳过可失败函数的错误文档

快速参考

基本文档注释

/// 通过UUID检索实体。
///
/// 从存储加载实体并验证访问权限。
/// 如果找到且可访问，返回[`Entity`]。
///
/// # 错误
///
/// - [`NotFound`] 如果实体不存在
/// - [`AuthorizationError`] 如果访问被拒绝
///
/// [`NotFound`]: EntityError::NotFound
/// [`AuthorizationError`]: EntityError::Authorization
pub fn get_entity(&self, id: EntityId) -> Result<Entity, Report<EntityError>> {

内部文档链接

/// 使用[`UserUpdateStrategy`]更新[`User`]。
///
/// 查看[`validation::user`]获取验证规则。
///
/// [`validation::user`]: crate::validation::user

文档模式

简单函数 (0-2 参数)

内联描述参数:

/// 处理`input`元素并返回过滤结果。
///
/// 获取`input`元素的集合，应用`filter_fn`，
/// 并返回只包含匹配元素的[`Vec`]。

复杂函数 (3+ 参数)

使用显式# Arguments部分:

/// 使用转换规则合并多个数据源。
///
/// # 参数
///
/// * `sources` - 要合并的数据源集合
/// * `rules` - 应用的转换规则
/// * `options` - 控制合并行为的配置
/// * `callback` - 每个合并项的可选函数

错误文档

/// # 错误
///
/// - [`WebAlreadyExists`] 如果web ID已被占用
/// - [`AuthorizationError`] 如果权限被拒绝
///
/// [`WebAlreadyExists`]: WebError::WebAlreadyExists
/// [`AuthorizationError`]: WebError::Authorization

模块文档

//! 实体管理功能。
//!
//! 主要类型:
//! - [`Entity`] - 核心实体类型
//! - [`EntityStore`] - 存储特性
//!
//! # 示例
//!
//! ```
//! use hash_graph::entity::Entity;
//! ```

带有错误处理的示例

/// # 示例
///
/// ```rust
/// let entities = get_entities_by_type(type_id)?;
/// assert_eq!(entities.len(), 2);
/// # Ok::<(), Box<dyn core::error::Error>>(())
/// ```

验证

cargo doc --no-deps --all-features

参考

references/function-documentation.md: 函数和方法文档模式
references/type-documentation.md: 类型、结构、枚举和特性文档
references/error-documentation.md: 错误条件和恐慌文档
references/examples-and-links.md: 示例和内部文档链接使用