35.1 文档

Rust 也支持使用特殊的文档注释来编写规范的文档。通过运行 cargo doc 命令会在 target/doc 目录下生成文档。该命令使用 rustdoc 工具把源码中的文档提取出来，生成易读的 HTML 等格式。运行 cargo doc --open 会直接在浏览器打开 html 文档查看。

普通的注释有两种，一种是用//开头的，是行注释，一种是/*...*/，是块注释。这些注释不会被视为文档的一部分。特殊的文档注释是///、//!、/**...*/、/*!...*/，它们会被视为文档。

跟 attribute 的规则类似：

///开头的文档被视为是给它后面的那个元素做的说明；
//!开头的文档被视为是给整个 crate 或模块做的说明。
/**...*/和/*!...*/也是类似的。

示例如下：

rust

//! 这块文档是给当前 crate 做的说明

mod foo {
    //! 这块文档是给 `foo` 模块做的说明

    /// 这块文档是给函数 `f` 做的说明
    fn f() {
    // 这块注释不是文档的一部分
    }
}

文档内部支持 markdown 格式。可以使用#作为一级标题。比如标准库中常用的几种标题：

rust

/// # Panics
/// # Errors
/// # Safety
/// # Examples

文档中的代码部分要用``符号把它们括起来。代码块应该用```括起来。比如：

rust

/// ```
/// let mut vec = Vec::with_capacity(10);
///
/// // The vector contains no items, even though it has capacity for more
/// assert_eq!(vec.len(), 0);
/// ```

Rust 文档里面的代码块，在使用 cargo test 命令时，也是会被当做测试用例执行的。这个设计可以在很多时候检查出文档和代码不对应的情况。

如果文档太长，也可以写在单独的 markdown 文件中。如果在单独的文件中写文档，就不需要再用///或者//!开头了，直接写内容就可以。然后再用一个 attribute 来指定给对应的元素：

rust

#![feature(external_doc)]

#[doc(include = "external-doc.md")]
pub struct MyAwesomeType;

docs.rs

docs.rs是 Rust 社区中广受欢迎的一个在线文档托管平台。它提供了 Rust 标准库、Crate 和 Rust 开源项目的在线文档，用户可以在该平台上查看这些文档并进行搜索。

Docs.rs 使用 nightly 版本的 Rust 编译器自动为发布到 crates.io 上的库构建文档。

通过 docs.rs，Rust 生态系统中的开发者可以方便地将他们的 Crate 文档托管在一个公共平台上，并且可以自动化地构建和更新文档以保持与代码同步。这有助于简化 Crate 的维护流程，并让 Crate 更易于使用和理解。

源代码位于github，具体的信息可以查看官网简介

35.1 文档 ​

docs.rs ​

35.1 文档

docs.rs