Rust能力养成之（16）文档化

 

前言

 

无需质疑，文档化(Documentation)在开发过程中非常重要。在开源社区，可以得到广泛应用的项目，其文档化水平都至少是合格的。我们的代码，对别人而言，应该是可读的，其中可以体现工作的目的，如此设计的原因，以及一些示例用法。可以这么说，具有完整自述文件README.md的项目，往往也都会运转良好。

因此，毫无例外，Rust社区非常重视文档，并在不同级别上提供了各种工具，以使编写代码文档变得容易。同时这些工具也考虑了用户体验方面的内容。对于编写文档，支持markdown，而Markdown是一种非常流行的标记语言，也是目前编写文档的标准语言。Rust有一个名为rustdoc的专用工具，它可以解析markdown文档注释，转换成HTML，并生成漂亮的、可搜索的文档页面。

 

编写文档

 

为了编写文档，我们通常用特定的符号来标记文档注释(doc comments)的开端。文档的编写方式与注释的编写方式类似，但是与普通注释的处理方式不同，并且由rustdoc进行解析。文档注释分为两个级别，并使用单独的符号来标记文档注释的开端。

 

• Item:这些注释用于模块中的条目(item)，比如结构、枚举声明 、函数、trait常量,等等。这种注释应该出现在条目的上方。对于单行注释，则以///开始，而多行注释以/**开始，以*/结束，这一点与很多语言类似。

• Module:这些是出现在根级别(root level)的注释，一般处于main.rs, lib.rs或任何其他模块(module)，并使用//!来标记一行注释的开始；对于多行注释而言，以/*!标识开始，以*/代表结束。可见，这种方式很适合给crate和代码示例做说明。

 

在doc注释中，可以使用通常的markdown语法来编写文档，还支持在反引号中编写有效的Rust代码(' ' 'let a = 23; ' ' ')，这也将成为文档测试的一部分。

前面用于写注释的符号实际上是#[doc="your doc comment"]这个属性的语法，一般称为文档属性(doc attributes)。当rustdoc解析///或/**行时，会转换为这些文档属性。另外，也可以使用这些doc属性编写文档。

 

生成并查看文档

 

要生成文档，我们可以使用项目目录中的cargo doc命令，该命令在target/doc/目录中生成一堆HTML文件和预定义的样式表。默认情况下，也会为crate的依赖项生成文档，我们可以通过运行Cargo doc --no-deps来告诉Cargo不要这样做。

要查看文档，可以在目标/doc目录中导航生成HTTP服务器。然后，将--open选项传递给cargo doc，就可以直接在默认浏览器中打开文档页面。

 

托管文档

 

生成文档之后，如果需要将其托管在某个地方供公众查看和使用，这里有三种方式:

 

• doc.rs:托管在crate.io上的包（crate）可以自动获得文档页面并托管在https://docs.rs上

• GitHub pages:如果crate在GitHub上，可以在gh-pages分支上托管文档

• 外部站点(External website):当然，更可以在自己管理的web服务器托管文档。Rust的标准库文档就是一个很好的例子:https://doc.rust-lang.org/std/

另外，如果项目文档超过两到三页，并且需要详细的介绍，那么有一个更好的选择来生成类似书籍的文档。这是通过使用mdbook项目来完成的。欲了解更多信息，请访问他们的GitHub页面https://github.com/rust-lang-nursery/mdBook。熟悉R语言的读者，应该可以发现，这个项目有点像bookdown。

 

文档属性(Doc attributes)

 

前面提到，我们编写的文档注释会被转换为文档属性的形式。除此之外，还有其他文档属性可以调整生成的文档页面，这些属性可以应用于crate级别或item级别。其基本的写法一般长成这样：#[doc(key = value)]。以下是一些非常有用的文档属性:

 

Crate级别文档属性

 

• #![doc(html_logo_url = "image url"):在文档页的左上角添加logo

• #![doc(html_root_url = "https://docs.rs/slotmap/0.2.1")]:为文档页面设置URL

• #![doc(html_playground_url = "https://play.rust-lang.org/")]：可以防止运行代码的run按钮，就可以在线上的Rust playground(第一篇中介绍过)中运行

 

Item级别文档属性

 

• #[doc(hidden)]: 假设已经为一个公共函数foo编写了文档，但只是给自己看的，不希望使用者查看该文档，那么可以使用这个属性来告诉rustdoc不用为foo生成文档。

• #[doc(include)]:这可以用来包含(include)来自其他文件的文档;如果文档很长，还可以将文档与代码分开。

如果要了解更多类似的属性，可以访问https://doc.rust-lang.org/beta/rustdoc/the-doc-attribute.html。

 

文档测试

 

在crate的公共api文档中包含代码示例，通常被认为是一个好的做法。不过，在维护这些示例时需要注意一点，因为你的代码可能会改变，也可能会忘记更新示例。那么，文档测试(doctest)也可以提醒更新示例代码。Rust允许您将代码嵌入到doc注释中的反引号中。然后，Cargo可以运行嵌入在文档中的示例代码，并将其视为单元测试套件的一部分。这意味着每次运行单元测试时都会运行文档示例，从可以起到催促更新的作用。还是很赞的吧。

文档化测试也是通过Cargo执行。这里创建了一个名为doctest_demo的项目来演示一下文档测试的东西。在lib.rs中，有以下代码:

// doctest_demo/src/lib.rs
//! This crate provides functionality for adding things//!//! # Examples//! ```//! use doctest_demo::sum;//!//! let work_a = 4;//! let work_b = 34;//! let total_work = sum(work_a, work_b);//! ```
/// Sum two arguments////// # Examples////// ```/// assert_eq!(doctest_demo::sum(1, 1), 2);/// ```pub fn sum(a: i8, b: i8) -> i8 {    a + b}

如您所见，模块和函数的文档测试之间的区别并不大，使用方式几乎相同。只是模块级的文档测试显示了crate的整体使用情况，涵盖了多个API表面，而函数级的文档测试只说明其所覆盖的特定函数。

 

在运行cargo test时，文档测试与所有其他测试一起运行。以下是我们在doctest_demo 的crate中，运行cargo test时的输出:

 

结语

 

讲过了文档化，下一篇，我们开始讲基准测试((Benchmark tests))。

 

主要参考和建议读者进一步阅读的文献

https://doc.rust-lang.org/book

1.Rust编程之道，2019， 张汉东

2.The Complete Rust Programming Reference Guide，2019， Rahul Sharma,Vesa Kaihlavirta,Claus Matzinger

3.Hands-On Data Structures and Algorithms with Rust，2018，Claus Matzinger

4.Beginning Rust ，2018，Carlo Milanesi

5.Rust Cookbook，2017，Vigneshwer Dhinakaran