# 进一步认识Cargo和Crates.io

Cargo 的其他高级功能：

- 使用发布配置来自定义构建
- 将库发布到crates.io
- 使用工作空间来组织更大的项目
- 从crates.io安装二进制文件
- 使用自定义的命令来拓展Cargo

## 采用发布配置自定义快捷键

默认设置：
文件名：Cargo.toml
opt-level的值从0到3，等级越高代表优化等级越高，代表需要更多的编译时间。

```toml
[profile.dev]   
opt-level = 0

[profile.release]   
opt-level = 3
```

## 采用crate发布到Crates.io

crates.io 用来分发包的源代码，所以它主要用来托管开源代码。

### 编写有用的文档注释

**文档注释**(documentation comments)，会生成HTML文档，这些HTML展示公有API文档注释的内容，意在让对库感兴趣的开发者理解如何**使用**这个crate，而不是它是如何被**实现**的。

#### 常用（文档注释）部分

`# Examples`Markdown标题在HTML中创建了一个以"Examples"为标题的部分。其他常用的文档注释有：

- **Panics**: 这个函数会`panic!`的场景。
- **Errors**: 如果这个函数返回`Result`，此部分的描述可能出现何种错误以及什么情况下会造成这些错误，这有助于调用者编写代码来采用不同的方式处理不同的错误。
- **Safety**: 如果这个函数使用`unsafe`代码，这一部分应该会涉及到期望函数调用者支持的确保`unsafe`块中的代码正常工作的不变条件(invariants)。

#### 文档注释作为测试

`cargo test`也会像测试那样允许文档中的代码，如果文档中的例子报错，会对使用者照成困扰。没有什么比有例子的文档更好的了，但最糟糕的莫过于写完文档后改动了代码，而导致例子不能正常工作。

#### 注释包含项的风格

还有另一种风格的文档注释，`//!`，为包含注释项的添加文档，而不是为了注释之后的项增加文档。通常位于crate根文件(通常是srs/lib.rs)或模块的根文件，为crate或模块整体提供文档。

### 使用pub use 导出合适的共有API

公有API的结构是你发布crate时需要考虑的。crate用户没有你那么熟悉其结构，并且如果模块层级过大他们可能会很难找到所需要的部分。

即使文件结构对于用于来说**不是**很方便，你也无须重新安排内部组织：可以选择使用`pub use`重导出(re-export)项来使公有结构不同于私有结构。重导出获取一个位置的公有项并将其公开到另一个位置，好像它就定义在这个新位置一样。

重导出示例:

```Rust
pub use self::addr:add_two;
```

使用示例：

```Rust
use rust_design_guide::add_two;

fn main() {
    add_two();
}
```