【Rust自学】14.2. 文档注释以及发布crate

喜欢的话别忘了点赞、收藏加关注哦（加关注即可阅读全文），对接下来的教程有兴趣的可以关注专栏。谢谢喵！(=^･ω･=)

14.2.1. crates.io

crates.io是一个面向 Rust 编程语言的官方包管理平台，类似于其他语言的包管理器（如 npm 对于 JavaScript，pip 对于 Python）。它的主要作用包括：

• 托管 Rust 库（crate）： 开发者可以在 Crates.io 上发布自己的 Rust 库，其他开发者可以通过它下载并使用这些库。
• 依赖管理： Rust 的构建工具和包管理器 Cargo 会从 Crates.io 下载所需的依赖包，用于简化项目开发。
• 搜索和发现： 用户可以在 Crates.io 上搜索已有的库，找到适合自己项目需求的解决方案。
• 版本控制和更新： crates.io支持版本管理，开发者可以上传新版本的库，用户也可以轻松更新依赖。

在第一章的猜数游戏中我们就使用了crates.io中的rand这个第三方包来获取随机数。我们不仅可以使用他人提供的crate,也可以发布自己的crate到crates.io供他人使用。

Rust 和 Cargo 具有使您发布的包更容易被人们找到和使用的功能。接下来我们将讨论其中一些功能，然后解释如何发布包。

14.2.2. 文档注释

使用///来写文档注释，文档注释用于生产项目的文档，它不同于//，//用于代码的标注，而文档注释是整个项目的注解。

这种文档是html文档，支持Markdown格式，它会显示公共的API的文档注释，通常是教读者如何使用API。

一般文档注释放置在被说明条目之前。

看个例子：

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

PS：在Markdown中，#是标题的标记，` ````是代码块的标记。

14.2.3. 生成html文档的命令

在终端中使用命令cargo doc会使用rustdoc工具（Rust安装自带），可以生成文档。它会把生成的文档放在target/doc目录下。

cargo doc --open会生成文档并在网页浏览器中打开结果：

14.2.4. 常用章节（部分）

以下是 crate 作者在其文档中常用的一些部分：

• # Example是示例部分，下面的代码块放示例代码

• Panic:正在记录的函数可能会出现恐慌的情况。不希望程序出现恐慌的函数调用者应确保在这些情况下不会调用该函数。

• Error:如果函数返回Result ，则描述可能发生的错误类型以及可能导致返回这些错误的条件对调用者很有帮助，以便他们可以编写代码以不同的方式处理不同类型的错误。

• Safety:如果函数调用unsafe （以后会讲），应该有一个部分解释为什么该函数不安全并涵盖该函数期望调用者维护的不变量。

14.2.5. 文档注释作为测试

文档注释中的代码块会在执行cargo test命令时作为测试来调用，会在测试结果中看到这部分：

   Doc-tests my_crate

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.27s

14.2.6. 为包含注释的项添加文档注释

//!将文档添加到外层条目，而不是添加到注释后面的项目。我们通常在crate根文件（按照惯例src/lib.rs）或模块内部使用这些文档注释来记录crate或整个模块：

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

这个例子中，添加了描述my_crate用途的文档，也就是对add_one的外层条目的注释。

这时候html文档也会跟着变化：

原文地址：https://blog.csdn.net/weixin_71793197/article/details/145273781

免责声明：本站文章内容转载自网络资源，如侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！