注释与文档注释¶

注释用于说明代码无法直接表达的原因、约束和设计决策。Rust 普通注释不会进入生成文档，文档注释则会被 rustdoc 解析，并可包含可编译测试的 Markdown 代码块。

普通注释¶

fn main() {
    // 协议要求毫秒，不能直接传入秒数。
    let timeout_ms = 5 * 1_000;

    /* 块注释可以跨行，
       也支持嵌套。 */
    println!("timeout = {timeout_ms}ms");
}

优先写简短的 // 行注释。不要复述 count += 1 是“计数加一”，应解释为何增加、单位是什么或哪个外部约束要求这样做。过时注释比没有注释更危险。

外部文档注释¶

/// 描述紧随其后的项目，常用于公开函数、结构体、枚举和字段：

/// 计算矩形面积。
///
/// # Examples
///
/// ```
/// let area = 3_u32 * 4_u32;
/// assert_eq!(area, 12);
/// ```
fn area(width: u32, height: u32) -> u32 {
    width * height
}

fn main() {
    println!("{}", area(3, 4));
}

真实库中的示例通常通过 crate 路径导入公开 API。运行文档测试和生成文档：

cargo test --doc
cargo doc --no-deps
cargo doc --open

常见章节包括 # Examples、# Errors、# Panics 和 # Safety。公开函数返回 Result 时说明错误条件；可能 panic 时说明触发条件；unsafe API 必须写清调用者要维持的不变量。

内部文档注释¶

//! 描述包含它的模块或 crate，通常写在文件开头：

//! 简单的单位转换工具。
//!
//! 本 crate 中所有长度均使用米作为基础单位。

/// 将千米转换为米。
pub fn kilometers_to_meters(value: f64) -> f64 {
    value * 1_000.0
}

对应的块形式是 /** ... */ 和 /*! ... */，但 Rust 项目通常更常见三斜线形式。

文档中的代码块¶

rustdoc 会把普通 Rust 代码块作为 doctest。仅编译不运行可标记 no_run，预期失败可标记 compile_fail，隐藏辅助行可在行首使用 #。不要随意使用 ignore 掩盖已损坏示例。

常见错误与工程说明¶

/// 必须放在被描述项目之前；文件或模块总览通常使用 //!。
私有实现不必机械补全 API 文档，但复杂不变量应留在最靠近实现的位置。
示例应短小、可运行，并与当前 API 同步；doctest 是防止文档腐化的低成本手段。
注释中不要保存密钥、内部地址、个人数据或临时调试信息。
公共 API 文档应描述行为和契约，而不是暴露可能变化的内部实现步骤。

检查清单¶

公共 API 是否说明用途、参数语义、错误和 panic 条件？
示例能否通过 cargo test --doc？
注释是否解释“为什么”，并仍与代码一致？