写给 Web 开发者的 Rust 语言入门教程（22.文档）

最后的叶子的奇妙小屋 2021-09-24

775

之前的文章：

0.引言

本章主要介绍 rust 自身的文档编写方法，以及文档工具的使用方法。

文档写法

rust 自带有一套强大而易用的文档体系，可以用于生成 crate 的接口文档，使用起来非常简单方便。

用于说明整个模块的文档，可以在文件开头用 //! 编写；对于文件内的函数、 trait 、 struct 、 enum 等的文档，可以在它们前面用 /// 编写。例如：

//! some helper functions


/// add two numbers
pub fn add(a: u32, b: u32) -> u32 {
    a + b
}

文档内容没有任何硬性要求，且可以使用 markdown 语法。例如：

//! some helper functions
//!
//! The `add` fn can add two *u32*.


/// add two numbers
///
/// The added numbers should not exceed *u32*.
///
pub fn add(a: u32, b: u32) -> u32 {
    a + b
}

文档写完后，使用 cargo doc 命令就可以生成文档了：

cargo doc

生成好的文档位于 target/doc/模块名/index.html ，用浏览器打开即可。

常见文档编写习惯

虽说具体的文档内容没什么限制，但一些好的习惯能（在大多数情况下）使文档更易读。

通常，文档的第一行是一句简洁的说明，例如：

/// add two numbers
pub fn add(a: u32, b: u32) -> u32 {
    a + b
}

对于简单的代码块，这样的一句话说明就已经够了。

需要注意的是，不应去描述每个参数（或字段等）分别是什么含义的！因为大多数情况下，通过名称和类型标注，很容易明白它们的含义，多加赘述会让文档变得过于冗长。

如果有些细节确实不太容易明白，或需要进一步说明一些使用时的注意事项，可以多加一些详细说明，例如：

/// add two numbers
///
/// The added numbers should not exceed *u32*.
///
pub fn add(a: u32, b: u32) -> u32 {
    a + b
}

也可以考虑再加上一些代码示例，例如：

/// add two numbers
///
/// The added numbers should not exceed *u32*.
///
/// ```
/// use my_doc::add; // my_doc 是 crate 名字
/// let sum = add(1, 2);
/// assert_eq!(sum, 3);
/// ```
///
pub fn add(a: u32, b: u32) -> u32 {
    a + b
}

在使用 cargo test 执行测试时，这种代码示例也会被测试，所以要注意 markdown 代码块里不能使用伪代码。

对于模块级别的文档，可以考虑重点说明这个模块里面有哪些部分是常用的或值得关注的。

//! some helper functions
//!
//! The `add` fn can add two numbers.

最后，文档并没有任何内容上的限制，可以根据实际情况决定写什么、不写什么。文档工具也会自动加上不少相关信息和链接，写文档时可以更简洁。

文档上还会展示其他一些模块信息，之后的文章将介绍。

数据库

文章转载自最后的叶子的奇妙小屋，如果涉嫌侵权，请发送邮件至：contact@modb.pro进行举报，并提供相关证据，一经查实，墨天轮将立刻删除相关内容。

写给 Web 开发者的 Rust 语言入门教程（22.文档）

评论