Rust 学习笔记 - 注释全解

这篇具有很好参考价值的文章主要介绍了Rust 学习笔记 - 注释全解。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

前言

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

单行注释

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

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

多行注释

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

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

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

/*
这是外层的多行注释。
/* 这是内层的多行注释 */
*/

文档注释

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

单行文档注释

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

/// 加上两个数
///
/// # 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 演示如下:

Rust 学习笔记 - 注释全解,Rust 学习笔记,rust,笔记,后端,开发语言,学习

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

Rust 学习笔记 - 注释全解,Rust 学习笔记,rust,笔记,后端,开发语言,学习

多行文档注释

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

/**
处理特定任务并返回结果的函数。

# 注意

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

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

模块注释

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

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

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

Rust 学习笔记 - 注释全解,Rust 学习笔记,rust,笔记,后端,开发语言,学习

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 浏览器打开后,呈现页面如下:

Rust 学习笔记 - 注释全解,Rust 学习笔记,rust,笔记,后端,开发语言,学习

结语

通过编写清晰和详细的文档注释,可以使代码更易于理解,并帮助其他开发者更好地利用你的代码或库。文章来源地址https://www.toymoban.com/news/detail-827662.html

参考资料

  • rust 圣经:https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
  • rust 实例:https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
  • rustdoc: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
  • rust RFC: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text

到了这里,关于Rust 学习笔记 - 注释全解的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • Rust语言从入门到入坑——(2)Rust在windows上搭建开发环境

    开始搭建一个适合在windows上运行的Rust环境。 Rust支持的程序语言很多:可详见官网介绍 本文章主要是在windowns下搭建开发环境 首先,需要安装最新版的 Rust 编译工具和 Visual Studio Code。 Rust 编译工具:https://www.rust-lang.org/zh-CN/tools/install Visual Studio Code:https://code.visualstudio.com

    2024年02月09日
    浏览(50)
  • 【Rust】Rust学习 第十三章Rust 中的函数式语言功能:迭代器与闭包

    Rust 的设计灵感来源于很多现存的语言和技术。其中一个显著的影响就是  函数式编程 ( functional programming )。函数式编程风格通常包含将函数作为参数值或其他函数的返回值、将函数赋值给变量以供之后执行等等。 更具体的,我们将要涉及: 闭包 ( Closures ),一个可以储

    2024年02月12日
    浏览(51)
  • 研读Rust圣经解析——Rust learn-4(函数,注释,控制流)

    函数的用处在于代码封装和复用 通过使用fn我们可以声明一个函数 和其他语言一样函数名称加括号 在Rust中我们可以为一个变量设定一个函数表达式以设定变量的值 相当于写成: 所有程序员都力求使其代码易于理解,不过有时还需要提供额外的解释,这就是注释 Rus

    2023年04月15日
    浏览(33)
  • Rust软件外包开发语言的特点

    Rust 是一种系统级编程语言,强调性能、安全性和并发性的编程语言,适用于广泛的应用领域,特别是那些需要高度可靠性和高性能的场景。下面和大家分享 Rust 语言的一些主要特点以及适用的场合,希望对大家有所帮助。北京木奇移动技术有限公司,专业的软件外包开发公

    2024年02月12日
    浏览(47)
  • Rust 注释规则

    单行注释有两种 // 和 /// 。 其中 /// 用在文档的头部,作为文档的一部分。 // 可以用在任何部分。 多行注释 /* */ 。

    2024年02月03日
    浏览(37)
  • Rust的注释与文档

    rust中//!和///有什么区别? 在 Rust 中, //! 和 /// 是特殊注释语法,用于文档注释(Documentation Comments)。它们用于编写文档,并生成 Rust 代码的 API 文档。 //! 用于编写模块级别的文档注释,通常放置在模块的开头。它允许您编写与整个模块相关的文档。这些注释会被 Rust 编译

    2024年02月07日
    浏览(57)
  • rust的函数和注释

    声明函数使用 fn rust使用snake case 命名规范,即 所有的字母都是小写的,单词之间使用下划线分开 函数的参数类型必须指明 rust函数体由一系列语句组成,可选择由一个表达式结束 rust是一个基于表达式的语言 语句是执行一些动作的指令 表达式会计算产生一个值 函数

    2024年02月16日
    浏览(29)
  • Rust 学习笔记(持续更新中…)

    运行 Rust 程序之前必须先编译,命令为: rustc 源文件名  - rustc main.rs 编译成功之后,会生成一个二进制文件 - 在 Windows 上还会生产一个 .pdb 文件  ,里面包含调试信息 Rust 是 ahead-of-time 编译的语言 - 可以先编译程序,然后把可执行文件交给别人运行(无需安装 Rust ) rustc

    2024年02月10日
    浏览(83)
  • Rust 学习笔记 - 变量声明与使用

    任何一门编程语言几乎都脱离不了:变量、基本类型、函数、注释、循环、条件判断,这是一门编程语言的语法基础,只有当掌握这些基础语法及概念才能更好的学习 Rust。 Rust 是一种强类型语言,但在声明变量时,不总是需要显式声明类型,这是因为 Rust 的编译器有类型推

    2024年02月19日
    浏览(40)
  • Rust 程序设计语言学习——基础语法

    Rust 语言是一种高效、可靠的通用高级语言。其高效不仅限于开发效率,它的执行效率也是令人称赞的,是一种少有的兼顾开发效率和执行效率的语言。 Rust 语言由 Mozilla 开发,最早发布于 2014 年 9 月。Rust 的编译器是在 MIT License 和 Apache License 2.0 双重协议声明下的免费开源软

    2024年01月22日
    浏览(50)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包