文档根元素 beans 必须匹配 doctype 根 null_【译文】Rust API 指南：文档

原文：Rust API Guidelines Chapter 4 Documentation

Crate级别的文档应非常详尽，并包含示例（C-CRATE-DOC）

见RFC1687.

所有条目都应有一个rustdoc示例（C-EXAMPLE）

每个公共模块，特型，结构，枚举，函数，方法，宏和类型定义都应具有一个示例，用于该功能的练习。

该准则应在合理范围内适用。

有时，附上另一个条目的适用示例的链接可能就足够了。例如，如果恰好一个函数使用特定类型，则可以在该函数或类型上编写单个示例后，从另一个链接到该示例。

示例的目的并不总是显示如何使用该条目。虽然读者希望了解如何调用函数，在枚举上进行匹配，以及一些基本任务。但是，一个示例最应该表明为什么要使用这个条目。

// 这是使用clone()的不良示例。它机械地显示*如何*
// 调用clone()，但没有显示出*为什么*要这样做。
fn main() {
    
    let hello = "hello";
​
    hello.clone();
}

示例使用？，不是try !，也不是unwrap（C-QUESTION-MARK）

不管喜欢与否，用户通常逐字复制示例代码。Unwrapping an error应该是用户需要做出的决定。

下面是这种常见的方式会构建易出错的示例代码。以＃开头的行是在构建示例时通过cargo test编译的，但不会出现在用户可见的rustdoc中。

/// ```rust
/// # use std::error::Error;
/// #
/// # fn main() -> Result<(), Box<dyn Error>> {
/// your;
/// example?;
/// code;
/// #
/// #     Ok(())
/// # }
///

函数文档应包括错误，恐慌和安全注意事项（