发布配置文件

$ cargo build 
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
$ cargo build --release
    Finished release [optimized] target(s) in 0.0s

准确记录你的包将帮助其他用户了解如何和使用它们，因此值得花时间编写文档。在第 3 章中，我们讨论了如何使用两个斜杠注释 Rust 代码，//。Rust 还有一种特定的注释类型用于文档，HTML 显示了针对程序员了解如何使用你的类别而不是如何实现你的 crate 的公共 API 项的文档注释内容。

文档注释使用三个斜杠，///，而不是两个，并支持 Markdown 语法进行格式化。在一个名为 my_crate 的 crate 中放置一个 add_one 函数的文档注释。

常用部分

我们使用了列表 14-1 中的 # 示例 Markdown 标题来创建一个具有标题“示例”的 HTML 部分。以下是 crate 作者在其文档中常用的一些其他部分

• 恐慌：函数可能引发恐慌的情况。不想让程序引发恐慌的函数调用者应确保在这些情况下不调用该函数。

• 错误：如果函数返回一个 Result，描述可能发生的错误类型以及可能引起这些错误返回的条件可能对调用者有所帮助，使他们能够编写代码以不同的方式处理不同类型的错误。

• 安全性：如果函数调用是 unsafe（我们在第 19 章中讨论了不安全性），则应有一个部分解释为什么函数是不安全的，并涵盖函数期望调用者维护的不变量。

大多数文档注释不需要所有这些部分，但这是一个很好的清单，提醒你用户可能感兴趣了解的代码方面。

文档注释作为测试

在文档注释中添加示例代码块可以帮助演示如何使用您的库，而且这样做还有一个额外的优势：运行cargo test将运行文档中的代码示例作为测试！没有什么比带有示例的文档更好，但没有什么比文档中的示例无法工作更糟糕，因为自文档编写以来代码已经发生了变化。如果我们运行cargo test，针对列表14-1中add_one函数的文档，我们将在测试结果中看到如下这样的一个部分

    Doc-tests package-manager
    
    running 1 test
    test src/lib.rs = add_one (line 5) ... ok
    
    test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 
        0 filtered out; finished in 0.9s

现在，如果我们更改函数或示例，使得示例中的assert_eq!导致panic，然后再次运行cargo test，我们会看到文档测试捕捉到示例和代码之间不一致的情况！

注释包含的项

文档注释的风格//!将文档添加到包含注释的项，而不是添加到注释后面的项。这些注释特别适用于描述crate和模块。使用它们来解释容器的主要目的，以帮助用户理解crate的组织结构。

使用pub use导出方便的公共API

您可以使用pub use重新导出项，以创建一个与您的私有结构不同的公共结构。重新导出将一个位置上的公共项变成另一个位置的公共项，就像它在另一个位置定义一样。