怎么说呢，

在上一篇文章中。我们学习了 Rust 的函数与返回值。

因为代码越来越多，仅仅让程序“能够运行”还不够。我们还需要让其他开发者，甚至未来的自己，能够快速理解代码的作用。

这时就需要使用注释。

Rust 中的注释类型

Rust 中的注释主要分为两类：

• 普通注释这方面，用于说明代码逻辑
• 文档注释这方面。用于生成 API 文档

今天聊聊详细说

• 单行注释
• 多行注释
• 文档注释 ///
• 模块文档注释 //!
• 文档代码示例
• cargo doc 的使用
• 文档测试
• 注释的常用方法

什么是注释？说起来，

使用者痛点：很多新手误以为注释会影响运行速度或占用内存。导致不敢写或随意写，

注释是写给开发者看的说明文字。编译器会忽略它们，不会把它们当作程序代码执行。

fn main {
// 输出欢迎信息
println!，怎么说呢，}

程序运行时只会执行下面这行：

println!，

为什么需要注释？

常见痛点：

• 团队成员看不懂复杂业务逻辑，需要反复沟通。
• 维护老项目时找不到实现细节，导致 bug 频发。
• 公共 API 缺少说明，使用者只能猜测调用方式。

再看几个作用，

• 解释复杂逻辑
• 说明特殊处理原因
• 记录函数或模块用途
• 提醒后续开发者注意事项
• 为公共 API 生成文档
• 帮助团队协作和项目维护

单行注释（//)

fn main {
// 定义使用者年龄
let age = 30;// 输出年龄
println!，}

从 // 开始直到本行结束，都会被视为注释。

行尾注释

fn main {
let port = 8080;// Web 服务端口
println!，}

# 痛点提示：If 注释放在行尾且说明文字较长，会降低可读性。建议改为独立一行：

fn main {
// Web 服务默认监听端口
let port = 8080;println，;}

连续多行单行注释（多个 //)

fn main {
// 这是一个简单的 Rust 程序
// 用于演示连续多行注释
// 程序会输出一条消息
println!
，}

块注释（)

/*
这里可以写多行说明
适合临时解释一段大段内容
*/
fn main {
println!，}

- 单行块注释放法：

//* 使用者默认年龄 *//
let age = 30;怎么说呢，println!，

块注释支持嵌套 

fn main {
/* 外层块开始
/* 内层块 */
继续外层块内容
*/
println!，}


# 痛点：有些语言不支持嵌套，导致临时屏蔽大段代码时只能手动添加前缀。Rust 的嵌套特性能省去这一步。

临时屏蔽代码 



从输出来看，


程序开始
程序结束
 

# 建议：Avoid 长期保留大量被屏蔽的旧代码；使用 Git 查看历史更使用较稳定。

普通 注 解只 在 源码 中 可见。

文 档 注 解 除 了 能 在 源码 中 说 明 功 能，还 能 通 过 Cargo 自动 生 成 HTML 文 档。

Rust 常 用 的 文 档 注 解 有 两 种 ： 


 /// 

 //!


它们 的 作 用 不 同。

使用 /// 为 函数 编 写 文 档 

 i32 { a + b }



此 文 档 属 于 add 函数。

为 公 共 函 数 编 写 文 档 

a第 一个 整数
/// - b第 二 个 整数
///
/// # 返回值
/// 返回 两 个 整数 相 加 后 的 结果。其实，pub fn add -> i32 { a + b }



这些 内容 会 被 cargo doc 转 换 为 网 页 文 档。

常 用 文 档章节 


# Examples 

# Arguments 

# Returns 

# Errors 

# Panics 

# Safety 


# 痛点：Cargo 默认 会 为 所有依赖 生 成 文 档，导致 项目 编译 时间 拉 长。

Examples 示例 

="" 两="" 个="" 和。="" 整数="" 的="" 计算="">
/// let result = add;/// assert_eq!，///
pub fn add -> i32 { a + b }



生成 的 文 档 中 会 显 示 可 执 行 示例。