Rust 学习笔记 - 注释全解

前言

和其他编程语言一样,Rust 也提供了代码注释的功能,注释用于解释代码的作用和目的,帮助开发者理解代码的行为,编译器在编译时会忽略它们。

单行注释

单行注释以两个斜杠 (//) 开始,只影响它们后面直到行末的内容。单行注释通常用于对代码行或代码块的短小说明。

rust 复制代码
// 这是单行注释的示例
fn main() {
    // 编译器会忽略这里的注释
    let x = 5; // 这是一个变量声明
}

多行注释

多行注释以一对 /**/ 符号之间的任何文本。它们可以跨越多行,并且可用于注释大块的代码或文本。

rust 复制代码
/*
这是一个多行注释的示例。
它可以跨越多行。
*/
fn main() {
    let y = 10;
    /*
    下面的代码虽然被注释,但可以展示一个代码块的结构:
    if y > 5 {
        println!("y is greater than 5");
    }
    */
}

值得注意的是,多行注释可以嵌套,这是 Rust 中的一个特性,允许在已经被注释的部分再添加注释。

rust 复制代码
/*
这是外层的多行注释。
/* 这是内层的多行注释 */
*/

文档注释

在 Rust 中,文档注释不仅对代码的阅读者提供了有价值的指导和解释,它们还被用来生成库的文档。这是通过 rustdoc 工具操作的,rustdoc 是 Rust 的官方文档生成工具,它能够从源代码中的文档注释生成 HTML 文档。

单行文档注释

单行文档注释使用三个正斜杠 ///。通常用来说明单个函数、结构体、枚举、模块或其他项:

rust 复制代码
/// 加上两个数
///
/// # Arguments
/// * `a` - A i32
/// * `b` - A i32
///
/// # Returns
/// * A i32
///
/// # Examples
/// ```
/// use docs_demo::math::add;
/// let a = 1;
/// let b = 2;
/// assert_eq!(add(a, b), 3);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

如果你的 IDE 支持的话,调用函数时可以看到函数注释,这里用的 VS Code 演示如下:

在上面的示例中,从 /// 开始的行,直到函数定义之前的部分都将成为这个函数的文档注释。rustdoc 工具将会捕获这些注释并用它们生成 HTML 文档。

多行文档注释

多行文档注释使用 /** ... */。如果注释说明比较长或者需要分段,那么这种方式就很有用:

rust 复制代码
/**
处理特定任务并返回结果的函数。

# 注意

这个函数对输入参数有特定的限制,比如...

# 示例
```
let output = another_function(10);  
println!("输出值: {}", output);
```
*/
fn another_function(param: i32) -> i32 {
    param * 2
}

模块注释

在模块或文件级别,可以使用 //! 来为整个模块或文件添加文档注释:

rust 复制代码
//! math crate
//!
//! `math` 是一个演示如何使用文件级文档注释的例子
//!
//! 它包含以下两个函数。
//! - add
//! - subtract

这通常位于文件的开始或模块的顶部。rustdoc 会将这一部分作为整个模块或 crate 的文档。

Markdown 支持

Rust 的文档注释支持使用 Markdown 语法来格式化文本。可以使用 Markdown 来添加标题、列表、代码块等格式化元素。rustdoc 工具将会解析 Markdown 来生成具有排版的文档。

生成文档

要生成文档,可以在项目目录下运行 cargo doc 命令。这会把 Rust 包以及其依赖项生成 HTML 文档,并将其放在 target/doc/<project name> 目录下。

复制代码
target
├── CACHEDIR.TAG
├── debug
└── doc
    ├── crates.js
    ├── docs_demo
    │   ├── all.html
    │   ├── fn.main.html
    │   ├── index.html                  # rust doc 入口文件
    │   ├── math
    │   └── sidebar-items.js
    ├── help.html
    ├── search-index.js
    ├── settings.html
    ├── src
    ├── src-files.js
    └── static.files

双击 index.html 浏览器打开后,呈现页面如下:

结语

通过编写清晰和详细的文档注释,可以使代码更易于理解,并帮助其他开发者更好地利用你的代码或库。

参考资料

相关推荐
魔芋红茶3 分钟前
spring-initializer
python·学习·spring
一个天蝎座 白勺 程序猿14 分钟前
Python(28)Python循环语句指南:从语法糖到CPython字节码的底层探秘
开发语言·python
西岭千秋雪_27 分钟前
Redis性能优化
数据库·redis·笔记·学习·缓存·性能优化
随便取个六字28 分钟前
GIT操作 学习
git·学习
chuanauc31 分钟前
Kubernets K8s 学习
java·学习·kubernetes
小张是铁粉35 分钟前
docker学习二天之镜像操作与容器操作
学习·docker·容器
持梦远方40 分钟前
C 语言基础入门:基本数据类型与运算符详解
c语言·开发语言·c++
zzywxc7871 小时前
AI 正在深度重构软件开发的底层逻辑和全生命周期,从技术演进、流程重构和未来趋势三个维度进行系统性分析
java·大数据·开发语言·人工智能·spring
小张是铁粉1 小时前
oracle的内存架构学习
数据库·学习·oracle·架构
HERR_QQ1 小时前
【unify】unify的微信小程序开发学习 (to be continued)
学习·微信小程序·小程序