Rust从入门到精通之入门篇：7.注释与文档

news/2025/3/30 3:30:07/

注释与文档

在本章中，我们将学习 Rust 中的注释和文档编写方法。良好的注释和文档是高质量代码的重要组成部分，它们帮助其他开发者（包括未来的你）理解代码的目的和工作方式。

注释类型

Rust 支持几种不同类型的注释，每种都有其特定的用途。

行注释

行注释以双斜杠（//）开始，一直延续到行尾。这是添加简短解释的最常见方式：

rust">// 这是一个行注释
let x = 5; // 这也是一个行注释

块注释

块注释以 /* 开始，以 */ 结束，可以跨越多行：

rust">/* 这是一个块注释它可以跨越多行 */
let x = /* 甚至可以在表达式中间 */ 5;

块注释在 Rust 中不太常见，通常只在临时注释大块代码时使用。

文档注释

Rust 有特殊的文档注释，用于生成文档。文档注释支持 Markdown 格式，可以包含代码示例、链接和其他格式化内容。

外部文档注释

外部文档注释以 /// 开始，通常放在它们描述的项（如函数、结构体等）之前：

rust">/// 计算两个数的和
///
/// # Examples
///
/// ```
/// let sum = add(1, 2);
/// assert_eq!(sum, 3);
/// ```
fn add(a: i32, b: i32) -> i32 {a + b
}
模块文档注释

模块文档注释以 //! 开始，通常放在模块的顶部，用于描述整个模块或 crate：

rust">//! # My Crate
//!
//! `my_crate` 是一个实用工具集合，提供了各种有用的功能。/// 这个函数属于 my_crate
fn my_function() {// 函数实现
}

文档注释的结构

一个好的文档注释通常包含以下部分：

  1. 简短描述：一句话概述项的功能
  2. 详细描述：更详细的解释，包括使用场景和注意事项
  3. 示例：展示如何使用该项的代码示例
  4. 参数：描述函数参数
  5. 返回值：描述函数返回值
  6. 错误：描述可能的错误情况
  7. Panics：描述可能导致 panic 的情况
  8. 安全性：描述安全性考虑（对于 unsafe 代码）

例如：

rust">/// 将一个字符串转换为大写
///
/// 这个函数接受一个字符串切片并返回一个新的 String，
/// 其中所有字母都转换为大写。非字母字符保持不变。
///
/// # Examples
///
/// ```
/// let result = my_crate::to_uppercase("hello");
/// assert_eq!(result, "HELLO");
/// ```
///
/// # Parameters
///
/// * `s` - 要转换的字符串切片
///
/// # Returns
///
/// 转换后的大写字符串
pub fn to_uppercase(s: &str) -> String {s.to_uppercase()
}

生成文档

Rust 提供了 rustdoc 工具来从文档注释生成 HTML 文档。通常，你可以使用 Cargo 来运行它：

cargo doc --open

这个命令会生成文档并在浏览器中打开它。--open 标志告诉 Cargo 在生成文档后自动打开浏览器。

文档测试

Rust 的文档系统有一个强大的特性：文档测试。在文档注释中的代码示例不仅仅是示例，它们也是测试。当你运行 cargo test，Rust 会编译并运行这些示例，确保它们正确工作。

rust">/// 返回输入值加一的结果
///
/// # Examples
///
/// ```
/// let five = 5;
/// let six = add_one(5);
/// assert_eq!(6, six);
/// ```
fn add_one(x: i32) -> i32 {x + 1
}

当你运行 cargo test 时，Rust 会测试这个示例是否正确。

隐藏测试代码

有时，你可能需要在文档测试中包含一些设置代码，但不希望它出现在生成的文档中。你可以使用 # 前缀来隐藏这些行：

rust">/// ```
/// # let x = 5;
/// let y = x + 1;
/// assert_eq!(y, 6);
/// ```

在生成的文档中，以 # 开头的行将被隐藏，但在测试时会被执行。

注释的最佳实践

何时使用注释

  • 解释为什么，而不是什么：代码本身应该清楚地表明它在做什么，注释应该解释为什么这样做。
  • 解释复杂的算法或逻辑：如果代码实现了复杂的算法，添加注释解释它的工作原理。
  • 标记待办事项或问题：使用 TODO 或 FIXME 注释标记需要改进的地方。

避免过度注释

不要为了注释而注释。如果代码已经很清晰，不需要额外的解释，那么不要添加多余的注释。过度注释可能会导致注释与代码不同步，反而造成混淆。

保持注释更新

当你修改代码时，确保同时更新相关的注释。过时的注释比没有注释更糟糕，因为它们会误导读者。

示例程序

让我们创建一个包含良好注释和文档的程序：

rust">//! # 温度转换库
//!
//! 这个库提供了在摄氏度和华氏度之间转换温度的功能。/// 将摄氏度转换为华氏度
///
/// # Examples
///
/// ```
/// let celsius = 0.0;
/// let fahrenheit = temp_converter::celsius_to_fahrenheit(celsius);
/// assert_eq!(fahrenheit, 32.0);
/// ```
///
/// # Parameters
///
/// * `celsius` - 摄氏度温度
///
/// # Returns
///
/// 对应的华氏度温度
pub fn celsius_to_fahrenheit(celsius: f64) -> f64 {// 使用标准公式：F = C * 9/5 + 32celsius * 9.0 / 5.0 + 32.0
}/// 将华氏度转换为摄氏度
///
/// # Examples
///
/// ```
/// let fahrenheit = 32.0;
/// let celsius = temp_converter::fahrenheit_to_celsius(fahrenheit);
/// assert_eq!(celsius, 0.0);
/// ```
///
/// # Parameters
///
/// * `fahrenheit` - 华氏度温度
///
/// # Returns
///
/// 对应的摄氏度温度
pub fn fahrenheit_to_celsius(fahrenheit: f64) -> f64 {// 使用标准公式：C = (F - 32) * 5/9(fahrenheit - 32.0) * 5.0 / 9.0
}/// 检查温度是否低于冰点（0°C）
///
/// # Examples
///
/// ```
/// assert!(temp_converter::is_freezing(-5.0));
/// assert!(!temp_converter::is_freezing(10.0));
/// ```
pub fn is_freezing(celsius: f64) -> bool {celsius < 0.0
}fn main() {// 测试温度转换函数let celsius = 25.0;let fahrenheit = celsius_to_fahrenheit(celsius);println!("{:.1}°C = {:.1}°F", celsius, fahrenheit);let fahrenheit = 68.0;let celsius = fahrenheit_to_celsius(fahrenheit);println!("{:.1}°F = {:.1}°C", fahrenheit, celsius);// 检查一些温度是否低于冰点let temperatures = [-10.0, 0.0, 10.0];for temp in temperatures.iter() {if is_freezing(*temp) {println!("{:.1}°C 低于冰点", temp);} else {println!("{:.1}°C 不低于冰点", temp);}}
}

练习题

  1. 为以下函数添加适当的文档注释，包括描述、示例和参数说明：
rust">fn is_prime(n: u32) -> bool {if n <= 1 {return false;}for i in 2..=(n as f64).sqrt() as u32 {if n % i == 0 {return false;}}true
}

  1. 创建一个简单的计算器模块，包含加、减、乘、除四个函数，并为每个函数添加适当的文档注释。

  2. 编写一个程序，包含至少三个函数，并使用不同类型的注释（行注释、块注释和文档注释）来解释代码。然后使用 cargo doc 生成文档并查看结果。

  3. 为以下结构体和方法添加文档注释：

rust">struct Rectangle {width: f64,height: f64,
}impl Rectangle {fn new(width: f64, height: f64) -> Rectangle {Rectangle { width, height }}fn area(&self) -> f64 {self.width * self.height}fn perimeter(&self) -> f64 {2.0 * (self.width + self.height)}
}
  1. 查看 Rust 标准库中的一些文档（例如 std::vec::Vec 或 std::string::String），分析它们的文档结构和风格，然后尝试模仿这种风格为自己的代码编写文档。

总结

在本章中，我们学习了：

  • Rust 中的不同类型的注释：行注释、块注释和文档注释
  • 如何编写良好的文档注释，包括描述、示例、参数说明等
  • 如何使用 cargo doc 生成文档
  • 文档测试的概念和用法
  • 注释的最佳实践

良好的注释和文档是专业软件开发的重要组成部分。它们不仅帮助其他开发者理解你的代码，也帮助你自己在未来回顾代码时理解你的思路。在下一章中，我们将学习 Rust 中的基本数据结构，如数组、向量和哈希表。


http://www.ppmy.cn/news/1583439.html

相关文章

JavaScrip-模版字符串的详解

JavaScrip-模版字符串的详解

1.模版字符串的详解 1.1 模版字符串的使用方法 在ES6之前&#xff0c;如果我们想要将字符串和一些动态的变量&#xff08;标识符&#xff09;拼接到一起&#xff0c;是非常丑陋的&#xff08;ugly) ES6允许我们使用模版字符串来嵌入变量或者表达式来进行拼接 首先&#xff0c;…
阅读更多...
用DrissionPage升级网易云音乐爬虫：更稳定高效地获取歌单音乐（附原码）

用DrissionPage升级网易云音乐爬虫：更稳定高效地获取歌单音乐（附原码）

一、传统爬虫的痛点分析 原代码使用requests re的方案存在以下局限性&#xff1a; 动态内容缺失&#xff1a;无法获取JavaScript渲染后的页面内容 维护成本高&#xff1a;网页结构变化需频繁调整正则表达式 反爬易触发&#xff1a;简单请求头伪造容易被识别 资源消耗大&am…
阅读更多...
Linux编译器gcc/g++使用完全指南：从编译原理到动静态链接

Linux编译器gcc/g++使用完全指南：从编译原理到动静态链接

一、gcc/g基础认知 在Linux开发环境中&#xff0c;gcc和g是我们最常用的编译器工具&#xff1a; gcc&#xff1a;GNU C Compiler&#xff0c;专门用于编译C语言程序g&#xff1a;GNU C Compiler&#xff0c;用于编译C程序&#xff08;也可编译C语言&#xff09; &#x1f4cc…
阅读更多...
为AI聊天工具添加一个知识系统 之150 设计重审 之15 完整方案及评估 之3

为AI聊天工具添加一个知识系统 之150 设计重审 之15 完整方案及评估 之3

本文要点 因果关系&#xff0c;逻辑关系&#xff0c;信念关系。 要点 集监管控于一身的 supervisor 监(EC理念 行列式 哈斯图&#xff1a;form&#xff08;介观链 - 介子 观察者 链式 连接路径 - 迁流函件&#xff09; :: kind) 管 (DP信念 参与矩阵 KV &#xff1a;t…
阅读更多...
HTTP 核心知识点整理

HTTP 核心知识点整理

1. HTTP 基础 ​定义&#xff1a;HTTP&#xff08;HyperText Transfer Protocol&#xff09;是应用层协议&#xff0c;基于 ​请求-响应模型&#xff0c;用于客户端&#xff08;浏览器&#xff09;与服务器之间的通信。​特点&#xff1a; ​无状态&#xff1a;每次请求独立&a…
阅读更多...
爬虫案例-爬取某站视频

爬虫案例-爬取某站视频

文章目录 1、下载FFmpeg2、爬取代码3、效果图 1、下载FFmpeg FFmpeg是一套可以用来记录、转换数字音频、视频&#xff0c;并能将其转化为流的开源计算机程序。 点击下载: ffmpeg 安装并配置 FFmpeg 步骤&#xff1a; 1.下载 FFmpeg&#xff1a; 2.访问 FFmpeg 官网。 3.选择 Wi…
阅读更多...
蓝桥杯嵌入式十六届模拟三

蓝桥杯嵌入式十六届模拟三

由硬件框图可以知道我们要配置LED 和按键 一.LED 先配置LED的八个引脚为GPIO_OutPut，锁存器PD2也是，然后都设置为起始高电平，生成代码时还要去解决引脚冲突问题 二.按键 按键配置，由原理图按键所对引脚要GPIO_Input 生成代码，在文件夹中添加code文件夹，code中添加fun.…
阅读更多...
长江学者答辩ppt_特聘教授ppt案例_校企联聘ppt制作_青年项目ppt模板

长江学者答辩ppt_特聘教授ppt案例_校企联聘ppt制作_青年项目ppt模板

“长江学者奖励计划”是高层次人才队伍建设的引领性工程。 为落实科教兴国战略&#xff0c;延揽海内外中青年学界精英&#xff0c;培养造就高水平学科带头人&#xff0c;启动实施了“长江学者奖励计划”。 / 长江学者答辩ppt案例 长江学者特聘教授答辩PPT设计 长江学者PPT项…
阅读更多...
最新文章

Copyright @ 2022~2023