注释和文档

好的代码会说话，好的程序员不写注释，这些都是烂大街的"编程界俚语"。但是，如果你真的遇到一个不写注释的项目或程序员，那一定会对它/他"刮目相看"。

在之前的章节我们学习了包和模块如何使用，在此章节将进一步学习如何书写文档注释，以及如何使用cargo doc生成项目的文档，最后将以一个包、模块和文档的综合性例子，来将这些知识融会贯通。

注释的种类

在Rust中，注释分为三类：

代码注释，用于说明某一块代码的功能，用户往往是同一个项目的协作开发者
文档注释，支持Markdown, 对项目描述、公共API等用户关心的功能进行介绍，同时还能提供示例代码，目标用户往往是想要了解你项目的人
包和模块注释，严格来说这也是文档注释中的一种，它主要用于说明当前包和模块的功能，方便用户迅速了解一个项目

通过这些注释，实现了Rust极其优秀的文档化支持，甚至你还能在文档注释中写测试用例，省去了单独写测试用例的环节，我直接好家伙！

代码注释

显然之前的刮目相看是打了引号的，想要去掉引号，该写注释的时候，就老老实实的，不过写时需要遵循八字原则：围绕目标，言简意赅，记住，洋洋洒洒那是用来形容文章的，不是形容注释！

代码注释方式有两种：

行注释 `//`

fn main() {// 我是Sun...// facelet name = "sunface"; let age = 18; // 今年好像是18岁
}

如上所示，行注释可以放在某一行代码的上方，也可以放在当前代码行的后方. 如果超出一行的长度，需要在新行的开头也加上//。

当注释行数较多时，你还可以使用块注释

块注释`/* ..... */`

fn main() {/*我是Sun... 淦，好长! */let name = "sunface"; let age = "???"; // 今年其实。。。挺大了
}

如上所示，只需要将注释内容使用/* */进行包裹即可。

你会发现，Rust的代码注释跟其它语言并没有区别，主要区别其实在于文档注释这一块，也是本章节内容的重点。

文档注释

当查看一个crates.io上的包时，往往需要通过它提供的文档来浏览相关的功能特性、使用方式，这种文档就是通过文档注释实现的。

Rust提供了cargo doc的命令，可以用于把这些文档注释转换成HTML网页文件，最终展示给用户浏览，这样用户就知道这个包是做什么的以及该如何使用。

文档行注释`///`

本书的一大特点就是废话不多，因此我们开门见山:

/// `add_one`将指定值加1
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {x + 1
}

以上代码有几点需要注意:

文档注释需要位于lib类型的包中，例如src/lib.rs中
文档注释可以使用markdown！例如 # Examples的标题，以及代码块高亮
被注释的对象需要使用pub对外可见, 记住：文档注释是给用户看的，内部实现细节不应该被暴露出去

咦？文档注释中的例子，为什看上去像是能运行的样子？竟然还是有assert_eq这种常用于测试目的的宏。嗯，你的感觉没错，详细内容会在本章后面讲解，容我先卖个关子。

文档块注释`/** ... */`

与代码注释一样，文档也有块注释，当注释内容多时，可以减少///的使用:

/** `add_two`将指定值加2.# Examples\`\`\`
let arg = 5;
let answer = my_crate::add_two(arg);assert_eq!(7, answer);
\`\`\`
*/
pub fn add_two(x: i32) -> i32 {x + 2
}

查看文档cargo doc

锦衣不夜行，这是中国人的传统美德。我们写了这么漂亮的文档注释，当然要看看网页中是什么效果咯。

很简单，运行cargo doc可以直接生成HTML文件，放入target/doc目录下。

当然，为了方便，我们使用cargo doc --open命令，可以在生成文档后，自动在浏览器中打开网页，最终效果如图所示:

非常棒，而且非常简单，这就是Rust工具链的强大之处。

常用文档标题

之前我们见到了在文档注释中该如何使用markdown，其中包括# Examples标题。除了这个标题，还有一些常用的，你可以在项目中酌情使用:

Panics: 函数可能会出现的异常状况，这样调用函数的人就可以提前规避
Errors: 描述可能出现的错误及什么情况会导致错误，有助于调用者针对不同的错误采取不同的处理方式
Safety: 如果函数使用unsafe代码，那么调用者就需要注意一些使用条件，以确保unsafe代码块的正常工作

话说回来，这些标题更多的是一种惯例, 如果你非要用中文标题也没问题，但是最好在团队中保持同样的风格

Rust语言圣经43 - 深度解读文档注释相关推荐

【Rust 日报】2022-01-09 又一个Rust中文教程《Rust语言圣经》
12个Rust的Tips 使用 Cow<str> 作为返回类型使用 Crossbeam channels 取代标准库使用 Scopeguard 实现类似 Golang 的延迟运算使用 ...
25岁阿里120W年薪架构师推荐学习的750页微服务架构深度解析文档
前言当前,微服务架构在国内正处于蓬勃发展的阶段,无论是大型互联网公司还是传统的IT企业,纷纷采用微服务架构构建系统. 在过去几年里,DevOps.云原生.面向演进式架构等理念已经深入人心,围绕微服务 ...
c语言之bbs管理系统,编写c语言的软件纯C语言编写图书管理系统WORD文档bbszp.doc...
编写c语言的软件纯C语言编写图书管理系统WORD文档bbszp 编写c语言的软件纯C语言编写图书管理系统WORD文档bbszp 导读:就爱阅读网友为您分享以下"纯C语言编写图书管理系统W ...
用JavaScript语言通过DOM遍历XML文档
实验结果要求如下: 解决步骤: 1. 首先是布局,左边用表格比较方便,右边是个div块. 2. 嵌入JavaScript脚本,由易到难,写定义全部显示的功能函数.显示姓名功能函数,显示属性功能函数 ...
易e语言从入门到精通文档手册教程下载
易e语言从入门到精通文档手册教程下载下载地址 https://download.csdn.net/download/fkew2009/10811499
Effective Dart 文档注释在Flutter项目中的实践
前言什么是注释? 在编程语言中,注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码. 也有一句话是这样说的:程序员都讨厌两件事,1.别人不写注释 2.自己写注释在开发者社区里,我不止 ...
注释（单行注释、多行注释、文档注释）
注释就是我们在写程序的时候会经常的加入注释,第一方便我们的阅读,第二用来提高程序的可读性.java语言允许程序员在程序中写上一些说明性的文字,这些说明性的文字就是注释.注释的内容不会出现在字节码中,即 ...
Javadoc（文档注释）详解
Java 支持 3 种注释,分别是单行注释.多行注释和文档注释.文档注释以/**开头,并以*/结束,可以通过 Javadoc 生成 API 帮助文档,Java 帮助文档主要用来说明类.成员变量和方法的 ...
建议：为所有导出的API元素编写文档注释。
如果要想使一个API真正可用,就必须为其编写文档.传统意义上的API文档是手工生成的,所以保持文档与代码同步是一件很繁琐的事情.Java语言环境提供了一种被称为Javadoc的实用工具,从而使这项任务 ...

Rust语言圣经43 - 深度解读文档注释

注释和文档

注释的种类

代码注释

行注释 `//`

块注释`/* ..... */`

文档注释

文档行注释`///`

文档块注释`/** ... */`

查看文档cargo doc

常用文档标题

Rust语言圣经43 - 深度解读文档注释相关推荐

最新文章

热门文章

Rust语言圣经43 - 深度解读文档注释

注释和文档

注释的种类

代码注释

行注释 //

块注释/* ..... */

文档注释

文档行注释///

文档块注释/** ... */

查看文档cargo doc

常用文档标题

Rust语言圣经43 - 深度解读文档注释相关推荐

最新文章

热门文章

行注释 `//`

块注释`/* ..... */`

文档行注释`///`

文档块注释`/** ... */`