Rust 注释全指南：从普通行注释到文档注释的完整用法

• 教程
• 文档

【免费下载链接】book

The Rust Programming Language

项目地址：https://gitcode.com/gh_mirrors/bo/book

点击查看免费下载

导读

注释是 Rust 源码中写给人类读者、而非编译器的说明文字。本篇以《The Rust Programming Language》仓库 src/ch03-04-comments.md 为主体，系统讲解 Rust 的普通注释写法（单行//、多行、行尾注释、独立行注释），并在此基础上结合仓库第 14 章内容纵深扩展文档注释（///与//!）、cargo doc文档生成与文档测试（doc test）等完整体系，帮助你写出既清晰易懂、又能自动生成 API 文档的 Rust 代码。

注释的本质：编译器忽略，人类阅读

所有程序员都希望自己的代码易于理解，但有时代码本身并不足以传达全部意图，需要额外的解释。在这种情况下，程序员会在源代码中留下注释（comments）——编译器会忽略它们，但阅读源码的人可能会觉得非常有用。

在 Rust 中，注释不会产生任何运行时行为：它不影响程序的编译结果、不占内存、不影响性能。注释的唯一服务对象是阅读源码的人（包括未来的你自己）。这正是 Rust 社区强调“注释是给读者看的”这一理念的原因。

单行注释：以//开头

Rust 中习惯性的注释风格是以两个斜杠开始注释，注释一直持续到该行结束：

// hello, world

//之后到行尾的所有内容都是注释，编译器会将其完全忽略。这是一个非常简单的注释示例，也是 Rust 中最常见的注释形式。

多行注释：每行都需要//

对于跨越多个行（超过一行）的注释，你需要在每一行都写上//，而不是像 C 语言那样使用/* ... */块注释。Rust 没有 C 风格的块注释语法（虽然/* */在某些场景下可用，但非惯用风格），惯用写法如下：

// So we're doing something complicated here, long enough that we need // multiple lines of comments to do it! Whew! Hopefully, this comment will // explain what's going on.

这种“每行一个//”的写法让注释的边界一目了然，也与 Rust 的代码风格保持一致。对于需要较长说明的场景，建议将长注释拆分成逻辑清晰的多行，每行保持合理的长度。

注释的两种放置位置

注释可以放在代码行的末尾（行尾注释），也可以放在被注释代码上方的独立行。仓库中的两个可运行示例恰好演示了这两种风格。

行尾注释

注释放在代码之后、同一行的末尾：

Filename: src/main.rs

fn main() { let lucky_number = 7; // I'm feeling lucky today }

这段代码来自仓库的 no-listing-24-comments-end-of-line/src/main.rs。注意，在let lucky_number = 7;这一语句的末尾，分号之后跟着// I'm feeling lucky today，解释了这个变量的含义（“幸运数字”）。

独立行注释

更常见的用法是让注释单独占据一行，放在它所注解的代码上方：

Filename: src/main.rs

fn main() { // I'm feeling lucky today let lucky_number = 7; }

这段代码来自仓库的 no-listing-25-comments-above-line/src/main.rs。这里注释// I'm feeling lucky today位于let lucky_number = 7;之前，解释即将声明的内容。

两种写法本身都合法，但 Rust 社区更推荐使用独立行注释：它让注释与代码的对应关系更清晰，也更易于在版本控制中追踪注释的变更。行尾注释适合简短、补充性的说明，而当注释内容较长时，独立行注释的阅读体验明显更好。

文档注释：///与//!

Rust 还有一种与普通注释不同的注释类型——文档注释（documentation comments）。普通注释服务的是阅读源码的开发者，而文档注释服务的对象是使用该 crate 的 API 用户：它会被rustdoc工具收集，生成 HTML 形式的 API 文档。原文档（src/ch03-04-comments.md）将这一话题指向了第 14 章“向 crates.io 发布 crate”一节（src/ch14-02-publishing-to-crates-io.md），下文据此展开。

用///为条目写文档注释

文档注释使用三个斜杠///（而非两个），并且支持Markdown 标记语法来格式化文本。///注释应紧贴在它所描述的条目之前。仓库 listing-14-01/src/lib.rs 给出了一个完整的示例：

/// Adds one to the number given. /// /// # Examples /// /// ``` /// let arg = 5; /// let answer = my_crate::add_one(arg); /// /// assert_eq!(6, answer); /// ``` pub fn add_one(x: i32) -> i32 { x + 1 }

这里先用一句话描述了add_one函数的功能，然后用# Examples标题开启一个 Markdown 章节，并提供了一段演示函数用法的代码。这些文本会被rustdoc渲染为结构化的 HTML 文档。

用cargo doc生成 HTML 文档

通过运行cargo doc，可以从这些文档注释生成 HTML 文档。该命令会运行随 Rust 分发的rustdoc工具，并将生成的 HTML 文档放在target/doc目录中。若想直接查看效果，可以运行：

cargo doc --open

cargo doc --open会构建当前 crate 的文档（以及所有依赖项的文档），并在浏览器中打开结果。

文档注释中常用的章节

仓库第 14 章还总结了 crate 作者们在文档注释中常用的几个 Markdown 章节，它们是写好 API 文档的实用清单：

• Panics：记录被文档化函数可能 panic 的场景。不希望程序 panic 的调用方应确保不在这些情况下调用该函数。
• Errors：如果函数返回Result，描述可能发生的错误种类以及导致这些错误的条件，帮助调用方针对不同错误编写不同的处理代码。
• Safety：如果函数调用是unsafe的，需要说明为什么该函数不安全，以及函数期望调用方维持的不变式（invariants）。

大多数文档注释并不需要包含以上所有章节，但这是一个很好的自查清单，用来提醒你关注用户（调用方）会关心的方面。

文档注释作为测试：doc test

在文档注释中加入示例代码还有一个额外的好处：运行cargo test时，文档注释中的代码示例会作为测试运行！没有什么比带示例的文档更好，但也没有什么是比“示例与代码不同步、无法运行”更糟的。cargo test会用类似下面的输出展示文档测试结果：

Doc-tests my_crate running 1 test test src/lib.rs - add_one (line 5) ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s

如果函数或示例被修改，导致示例中的assert_eq!panic，再次运行cargo test就能发现文档示例与代码已经不同步——这正是文档测试的意义所在：文档始终与真实代码保持一致。

用//!为容器条目写文档注释

文档注释还有一种//!风格：它把注释所对应的文档附加到包含该注释的条目上，而不是其后的条目。这类注释通常用在 crate 根文件（按惯例为src/lib.rs）或模块内部，用来描述整个 crate 或整个模块。

仓库 listing-14-02/src/lib.rs 演示了在src/lib.rs文件开头添加//!注释、描述整个 crate 的做法：

//! # My Crate //! //! `my_crate` is a collection of utilities to make performing certain //! calculations more convenient. /// Adds one to the number given. // --snip-- /// /// # Examples /// /// ``` /// let arg = 5; /// let answer = my_crate::add_one(arg); /// /// assert_eq!(6, answer); /// ``` pub fn add_one(x: i32) -> i32 { x + 1 }

注意：//!之后没有任何“其后的条目”，因为它使用//!而非///，所以它描述的是包含这条注释的条目——在这里就是src/lib.rs文件本身，即 crate 根，也就是整个 crate。运行cargo doc --open后，这些注释会显示在my_crate文档的首页、crate 公共条目列表的上方。容器内文档注释尤其适合描述 crate 与模块，用来向用户解释容器的整体用途，帮助用户理解 crate 的组织结构。

小结：普通注释与文档注释的分工

注释类型	语法	服务对象	用途
普通行注释	//	阅读源码的开发者	解释代码意图、记录上下文
行尾注释	// ...（代码行末尾）	阅读源码的开发者	简短补充说明
独立行注释	// ...（代码行上方）	阅读源码的开发者	惯用风格，注解下方代码
文档注释（条目级）	///	crate 的用户	为公共 API 条目生成 HTML 文档
文档注释（容器级）	//!	crate 的用户	为 crate/模块整体生成文档

掌握这套注释体系后，你的 Rust 代码将同时满足两个层次的需求：普通注释帮助协作者快速理解实现，文档注释则借助cargo doc与cargo test自动产出始终与代码同步的 API 文档。完整示例代码可在仓库的 listings/ch03-common-programming-concepts/no-listing-24-comments-end-of-line/src/main.rs、listings/ch03-common-programming-concepts/no-listing-25-comments-above-line/src/main.rs 以及 listings/ch14-more-about-cargo/listing-14-01/src/lib.rs、listings/ch14-more-about-cargo/listing-14-02/src/lib.rs 中直接查阅与运行。

赞分享

• 教程
• 文档

【免费下载链接】book

The Rust Programming Language

项目地址：https://gitcode.com/gh_mirrors/bo/book

点击查看免费下载

相关推荐

• Roc 注释与文档注释实战指南：从 `` 单行注释到 ` ` 文档注释的完整规则

  Roc 注释与文档注释实战指南：从 单行注释到 文档注释的完整规则 本篇围绕 Roc 语言参考文档中的注释章节展开，讲清两类注释的精确语法规则：普通单行注释（

• PRQL 注释语法详解：`` 行注释、文档注释与词法实现

  PRQL 注释语法详解： 行注释、文档注释与词法实现 本篇指南围绕 PRQL 官方语法参考中的注释规则展开：PRQL 使用字符 表示注释直到行尾，且没有独立的多

  后端

• novelWriter 注释系统完全指南：`%` 普通注释、Synopsis、脚注与忽略文本

  novelWriter 注释系统完全指南： % 普通注释、Synopsis、脚注与忽略文本 novelWriter 是一款专为小说写作设计的开源纯文本编辑器。它

  桌面应用