注释

// 到行尾。/* */ 是块注释，可以嵌套。注释解释「为什么」，不要重复代码已经表达的「做什么」。

rust

let timeout_ms = 30_000; // 上游约定超时，不是客户端默认值

文档注释

/// 写在项的上方，描述该项。//! 写在模块或 crate 内部，描述当前包围项。

rust

//! 配置解析。

/// 读取配置文件。
///
/// 路径不存在时返回 `io::Error`。
pub fn load(path: &str) -> std::io::Result<String> {
    std::fs::read_to_string(path)
}

文档注释是 Markdown，里面的代码块会作为文档测试编译。cargo doc 生成 HTML；cargo test 跑文档示例。

普通注释不会进入 rustdoc。临时禁用代码用版本管理，不要大段注释掉旧实现。