手把手带你写 Rust 文档

Rust参考手册 中文版(带完整目录) 官网最新翻译。 立即下载

手把手带你写 Rust 文档

在 Rust 中,文档不是代码的“附属品”,而是程序开发的一部分。Rust 为文档提供了原生的工具链支持,达到文档即代码、文档即测试的效果,这也是为什么 Rust 生态的库普遍有极高的文档质量。这篇文章会手把手带你写 Rust 文档,从基础语法、高级技巧,到最佳实践,写出符合 Rust 社区规范、可维护、高可用性的技术文档。

rustdoc 入门

Rust 文档的核心工具是 rustdoc,它是 Rust 官方内置的文档生成器,和 Cargo 深度集成,可以通过下面的命令使用:

rustdoc --version
# cargo doc 是调度 rustdoc 的便捷封装
cargo doc --version

命令速查

在项目根目录执行以下命令,就能完成文档的生成、预览和测试:

命令作用
cargo doc生成当前项目及所有依赖的文档
cargo doc --open生成文档并自动在浏览器打开预览
cargo doc --no-deps仅生成当前项目的文档,跳过依赖,大幅提升生成速度
cargo test --doc文档测试,会运行文档中的示例代码
cargo doc --offline离线生成文档,无需网络连接

文档注释语法

Rust 严格区分了普通注释和文档注释:普通注释是给代码维护者看的,不会被 rustdoc 解析,而文档注释是给用户看的,会被渲染到文档页面中。

四种注释的区别与用法

注释语法类型作用范围用途
// 内容普通行注释仅代码内部给维护者写的代码说明、TODO 等
/* 内容 */普通块注释仅代码内部多行的代码内部说明
/// 内容行文档注释紧随其后的项(函数、结构体、枚举等)给公开的 API 项写文档
/** 内容 */块文档注释紧随其后的项多行的 API 项文档,用法和 /// 一致
//! 内容模块级行文档注释所在的模块写在文件顶部,给当前模块写文档

第一行文档注释

我们先给一个简单的加法函数写文档,如下所示:

/// 计算两个整数的和,返回相加后的结果
///
/// 这是一个基础的整数加法函数,支持正负数、零的运算,
/// 不会做溢出检查,溢出行为遵循 Rust 整数溢出规则
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

执行 cargo doc --open,你就能在文档中看到这个函数的完整说明,rustdoc 会自动把注释内容渲染到函数的详情页中。

add函数注释文档

Markdown 的支持

rustdoc 对 Markdown 的支持还是比较全面的,包括代码块(带语法高亮)、列表、链接、表格等标准的 Markdown 语法。

基础 Markdown 语法

你可以在文档注释中使用所有常用的 Markdown 语法:

  • 标题:# 一级标题、## 二级标题,推荐二级及以下标题用于文档内部分段
  • 列表:有序列表 1. xxx、无序列表 - xxx
  • 代码块:用于写可运行的示例
  • 强调:**加粗**、*斜体*
  • 链接:[链接文本](链接地址)
  • 表格:常用于参数对比、特性说明等
  • 引用块:> 内容,常用于提示、警告信息

文档内链接(Intra-doc Links)

这是 Rust 文档的特性之一:你可以在文档中直接链接到当前 crate、标准库、其他 crate 的任意 API 项,用户点击就能跳转到对应页面。

语法比较简单,直接用[项名]即可完成链接,rustdoc 会自动解析路径并生成跳转链接:

/// 数学运算相关的错误类型枚举
#[derive(Debug, PartialEq, Eq)]
pub enum MathError {
    /// 除零错误,当除数为 0 时触发
    DivideByZero,
    /// 整数溢出错误
    Overflow,
}

/// 整数除法运算,返回商或错误
///
/// # Errors
/// 当除数 `b` 为 0 时,返回 [MathError::DivideByZero]
pub fn divide(a: i32, b: i32) -> Result<i32, MathError> {
    if b == 0 {
        return Err(MathError::DivideByZero);
    }
    Ok(a / b)
}

上面的例子中,[MathError::DivideByZero] 会自动生成跳转到该枚举项的链接,用户点击就能看到对应的定义和说明。

文档即测试

Rust 文档中最惊艳的功能之一就是文档测试(Doctest),这是其他编程语言中基本没有的功能。rustdoc 会把你文档里的 rust 代码块,当成单元测试来编译运行。这也就解决了文档和代码不同步的痛点,只要你改了代码,文档里的示例跑不通,测试就会直接报错,强制你同步更新文档。

第一个文档测试

我们给 add 函数的文档加上可运行的测试:

/// 计算两个整数的和,返回相加后的结果
///
/// # 示例
/// ```rust
/// use doc_example::add;
///
/// // 基础加法
/// assert_eq!(add(2, 3), 5);
/// // 正负数相加
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

执行 cargo test --doc,你会看到如下输出:

running 1 test
test src/lib.rs - add (line 22) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

隐藏辅助代码

很多时候,示例需要一些导入、main 函数等辅助代码,但这些代码会让文档变得冗余。你可以用 # 开头的行,标记这段代码会被编译运行,但不会渲染在文档中:

/// 除法运算示例
///
/// ```rust
/// # use doc_example::{divide, MathError};
/// # fn main() -> Result<(), MathError> {
/// let result = divide(10, 2)?;
/// assert_eq!(result, 5);
/// # Ok(())
/// # }
/// ```

渲染后的文档只会显示核心的两行代码,隐藏的 use、main 函数会在测试时正常运行,完美解决了 Result 类型的错误处理问题。

测试属性标记

你可以在代码块的开头添加属性,控制测试的行为:

属性作用
rust,should_panic标记该示例预期会 panic,测试时 panic 才算通过
rust,ignore忽略该示例,不编译不运行(常用于展示性代码)
rust,no_run只编译不运行(常用于网络 IO、文件操作等无法自动化测试的场景)
rust,compile_fail预期该代码编译失败,测试时编译不通过才算通过

示例如下:

/// 除零场景示例
///
/// ```rust,should_panic
/// use doc_example::divide;
///
/// // 除零会触发 panic
/// divide(10, 0).unwrap();
/// ```

非 Rust 代码块

如果你需要展示其他格式的内容,比如 JSON、文本、Shell 命令,只需要指定对应的语言标识,rustdoc 就不会把它当成测试:

/// 配置文件格式示例
///
/// ```toml
/// [math]
/// precision = 10
/// enable_overflow_check = true
/// ```

渲染 Mermaid 流程图

rustdoc 并不支持原生渲染 Mermaid 流程图,但是我们可以使用 aquamarine 这个库来达成效果,它是 rustdoc 的过程式宏扩展。

步骤一:添加依赖
cargo add aquamarine
步骤二:使用 Mermaid 流程图
#[cfg_attr(doc, aquamarine::aquamarine)]
/// 计算器运算流程
///
/// ```mermaid
/// graph LR
/// A[设置初始值] --> B[加法运算]
/// B --> C{是否除零?}
/// C -->|否| D[除法运算]
/// C -->|是| E[返回除零错误]
/// D --> F[输出最终结果]
/// ```
pub fn example() {}

渲染后的效果如下:

计算器运算流程

文档属性

Rust 提供了一系列 #[doc] 属性,让开发者可以精细化控制文档的渲染、可见性、搜索等行为,满足复杂场景的需求。

属性作用示例
#[doc = "内容"]动态生成文档内容,常用于宏生成的代码#[doc = concat!("这是", "动态生成", "的文档")]
#[doc(hidden)]隐藏该项,不渲染在文档中(用于内部实现)
#[doc(alias = "别名")]#[doc(alias = “别名”)] 给项添加搜索别名,用户搜索别名也能找到该项
#[doc(inline)]内联重导出项的文档,用户无需跳转就能看到
#[doc(no_inline)]不内联文档,点击跳转到原文档页面
#[cfg(doc)]仅在生成文档时编译该段代码
#![deny(missing_docs)]强制所有公开项必须有文档,缺失则编译报错写在 lib.rs 顶部,用于团队规范约束

最佳实践

Rust 社区有一套公认的文档规范,如下所示:

  • 一句话摘要:文档的第一行必须是一句话,精准概括这个项的核心作用
  • 详细描述:补充适用场景、设计思路、边界情况,告诉用户“什么时候用、什么时候不该用”
  • 示例优先:先给可运行的核心示例,再讲参数、返回值等细节
  • 专项说明:按需添加 # Parameters、# Returns、# Errors、# Panics、# Safety、# Performance 等专项章节
  • 公开项必写文档:所有 pub 的项都必须有文档,用 #![deny(missing_docs)] 强制约束
  • 文档和代码同步:改了代码不改文档,文档测试就是为了解决这个问题,确保每个示例都能跑通
  • unsafe 函数必须写 Safety 说明:这是 Rust 社区的硬性规范,所有 unsafe 函数必须写清楚调用者需要遵守的安全约束

最后,想要写出高质量的文档,最好的方法就是学习顶级开源库的写法,比如 Rust 标准库文档,它应该是最权威的文档规范范本了,另外,像 serde、tokio、anyhow 等库的文档也值得拿来学习。

总结

Rust 文档的核心,从来都不是语法和工具,而是“站在用户的角度思考”,你写的每一行文档,都是为了让用户能快速理解、正确使用你的代码。

rust最新中文全文档 最新最全介绍,高清文档,不容错过! 立即下载

相关推荐

安装keil5(MDK)及导入pack包教程

首先说明的是我安装的Keil版本为Keil V5.29.0.0 1、安装软件 右键管理员权限运行安装包 设置安装路径以及pack的存放路径 随意输入First Name和E-mail 安装驱动 完成软件安装,然后可以先关闭弹出的Pack Install(一会再添加) 2、激活一下软件 打开桌面的Keil File → License Management(我之前注册过了) 右...

hrx-@@ 10万+

Rust 本地文档的使用:rustup doc

Rust 本地文档的使用:rustup doc

一起coding,一起嗨。 2190

VTK 9.2.0 在 Windows 10 上编译全记录:从 CMake 配置到 VS2019 项目生成(附 Qt 环境变量避坑点)

本文详细记录了VTK 9.2.0在Windows 10上的编译全过程,从CMake配置到VS2019项目生成,特别强调了Qt环境变量的避坑点。通过实战步骤和调试技巧,帮助开发者顺利完成VTK编译,适用于三维可视化开发。

weixin_30082367的博客 365

【Rust】包和模块,文档注释,Rust格式化输出

模块是Rust的代码构成单元。Rust 出于安全的考虑,默认情况下,所有的类型都是私有化的,包括函数、方法、结构体、枚举、常量,就连模块本身也是私有化的。被引入到当前模块中时,它的可见性自动被设置为私有的,如果你希望允许其它外部代码引用我们的模块项。宏接受的是可变参数,第一个参数是一个字符串常量,它表示最终输出字符串的格式,包含其中形如。其实就是引用自身模块中的项,也就是说和我们之前章节的代码类似,都调用同一模块中的内容。目录下,每一个文件都是独立的二进制包,同时也会包含一个库包,该包只能存在一个。

小米子的成长日记 1122

CNN卷积神经网络手写数字识别实例及代码详解

本文的代码来自githup的Deep Learning的toolbox,是用Matlab实现的。感谢该toolbox的作者付出和分享。 我在应该该代码进行训练时,出现一些报错,如expand函数应用不对,flipall函数未定义等问题,对这些问题进行了修正,完成网络训练和验证。 本文mnist_uint8.mat的获取可以参照我的另一篇博客:MNIST数据库处理--matlab生成mnist_

VivienFu的专栏 6万+

2025-08-19利用opencv检测图片中文字及图片的坐标

该代码实现了图片中中文文本的检测与位置计算功能。主要使用CnOcr库进行OCR识别,结合OpenCV和PIL库处理图像。功能包括:1)检测图片中的中文文本及位置坐标;2)计算每个文本的像素宽度和高度;3)在原图上绘制文本边界框并标注识别结果。代码通过put_chinese_text函数解决中文显示问题,最终输出各文本内容、坐标位置及尺寸信息。适用于需要获取图片中文字精确位置的应用场景。

m0_58149406的博客 397

Rust的注释与文档

因此,在编写代码和文档时,建议遵循约定的标记位置,以确保生成的文档能够正确呈现和展示特殊标记的内容。是的,您可以在自定义样式中使用任何 CSS 属性来自定义生成的 API 文档的样式。在生成的 API 文档中,特殊标记的位置通常是固定的,遵循一定的约定和规范。在生成文档时,这些标记将被解析器处理,并以适当的方式呈现在生成的 API 文档中。您可以使用这些选项来调整生成的文档以满足特定的需求。在 Rust 中,生成的 API 文档的样式和呈现方式通常是由 Rust 的标准库提供的文档生成工具决定的,如。

techdashen的博客 771

国际参考电离层2020模型Matlab(IRI-2020)

国际参考电离层 (IRI) 是一个国际项目 由空间研究委员会 (COSPAR) 和国际 无线电科学联盟 (URSI)。这些组织组成了一个工作组 (在 60 年代后期产生了电离层的经验标准模型, 基于所有可用数据源 (几个稳步改进的版本 模型已经发布。电子密度、电子温度、离子温度、 离子组成(O+、H+、He+、N+、NO+、O+2、簇离子)、赤道垂直离子漂移、垂直电离层电子含量(vTEC;

weixin_44392003的博客 4885

Rust 文档生成与发布

通过良好的文档和发布流程,可以确保项目的可维护性和社区的接受度,为其他开发者提供更好的使用体验。RustDoc 是 Rust 自带的文档生成工具,可以通过注释生成详细的 API 文档。RustDoc 会解析项目中的文档注释,并生成 HTML 格式的文档。在软件开发中,良好的文档和发布流程对项目的可维护性和社区的接受度至关重要。本节将深入探讨如何使用 RustDoc 生成项目文档,以及如何将项目发布到 crates.io,包括一些高级技巧和最佳实践。:确保在发布前生成并检查文档,以帮助其他开发者使用您的库。

好看资源网的博客 2125

vCenter6.7证书过期导致503报错的全面修复指南:从STS证书更新到SSL信任修复

本文详细解析了VMware vCenter 6.7因STS证书过期导致503服务不可用错误的根本原因,并提供了从诊断、更新STS证书到修复SSL信任链的完整解决方案。通过命令行工具检查证书状态,使用官方脚本更新过期STS证书,并利用lsdoctor工具修复深层SSL信任问题,最终指导用户使用certificate-manager彻底重置所有证书,帮助管理员快速恢复vCenter服务。

pz890123的博客 1296

从DWS到设备树:MTK平台LK阶段GPIO初始化的隐秘路径与调试实战

本文深入探讨了MTK平台LK阶段GPIO初始化的完整流程,揭示了从DWS配置到设备树生成的隐秘转换路径。通过分析MT6768等平台的启动框架,提供了针对preloader到LK阶段GPIO初始化异常的实战调试方法与最佳实践,帮助开发者有效解决硬件与软件配置不匹配的常见问题。

h9j8k7l6m5n的博客 1003

Rust 教程项目文档

Rust 教程项目文档 项目的目录结构及介绍 tuto-rust-fr/ ├── README.md ├── src/ │ ├── main.rs │ ├── lib.rs │ └── ... ├── Cargo.toml └── ... README.md: 项目介绍和使用说明。 src/: 包含项目的源代码文件。 main.rs: 主程序入口文件。 lib.rs: 库文件,用...

gitblog_00245的博客 443

YOLOv5改进系列(4)——添加ECA注意力机制

手把手教你在YOLOv5中加入ECA注意力机制,文内含两种方法,小白也能看懂!

路人贾的博客 8548

手把手带你写 Rust 测试

Rust 从语言层面内置了一套开箱即用、零第三方依赖的测试框架,原生支持单元测试、集成测试、文档测试三大核心场景,实现了开发即测试、文档即测试的理念。

github_28443763的博客 433

文档:亲测可用解决vnc灰屏,黑屏,鼠标大黑叉情况

主要解决vnc-viewer灰屏,黑屏,鼠标大黑叉等现象,详细见文档。

STM32F407中文手册

STM32f407中文手册 本参考手册面向应用开发人员,提供有关使用 STM32F405xx/07xx、STM32F415xx/17xx、 STM32F42xxx 和 STM32F43xxx 微控制器存储器与外设的完整信息。STM32F405xx/07xx、STM32F415xx/17xx、STM32F42xxx 和 STM32F43xxx 构成一个微 控制器系列,各产品具有不同的存储器大小、封装和外设。有关订购信息以及器件的机械与电气特性,请参见数据手册。有关 ARM Cortex™-M4F 内核的信息,请参见《Cortex™-M4F 技术参考手册》。

rust生成html文档

在docs.rs看到的文档基本都是由这种方式生成的。

weixin_62799021的博客 973

VC中sqlite的使用

在VC中对sqlite的使用,实现数据库大批数据的快速插入,读取数据库中的数据在ListCtrl中显示

《Rust语言圣经》Rust教程笔记33:2.Rust基础入门(2.13Rust注释Rust文档注释Rust文档测试文档搜索别名)///、/** ... */、cargo doc、cargo test

在 Rust 中,注释分为三个主要类型:代码注释、文档注释、包和模块注释,每个注释类型都拥有两种形式:行注释和块注释,熟练掌握包模块和注释的知识,非常有助于我们创建工程性更强的项目。如果读者看到这里对于包模块还是有些模糊,强烈建议回头看看相关的章节以及本章节的最后一个综合例子。

Dontla的博客 2403

Devexpress16.2.6破解工具

Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具

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

在crates.io上,我们不仅可以使用他人提供的`crate`,也可以发布自己的`crate`到供他人使用。非常类似于python的pip。

A Rookie in San Domenico School 1470

rust-std:Rust标准库中文文档,助力中文开发者深入Rust编程

rust-std:Rust标准库中文文档,助力中文开发者深入Rust编程 项目介绍 在编程语言的海洋中,Rust以其安全、并发、实用的特性备受瞩目。然而,对于中文开发者来说,语言的学习和理解往往受限于文档的英文表述。为了让中文开发者更好地掌握Rust编程,rust-std项目应运而生。这是一个专注于Rust标准库的中文文档项目,旨在为中文开发者提供一个全面、准确的Rust标准库中文学习资源。 项目...

gitblog_00052的博客 1005

探索Rust文档新境界:Doxidize

探索Rust文档新境界:Doxidize 在编程的世界里,清晰、高效的文档是连接开发者与代码的桥梁。今天,让我们一起深入了解一个为Rust项目量身定制的创新工具——Doxidize,它正以一股东风,革新我们编写文档的方式。 项目概览 Doxidize,作为一个新兴的文档生成工具,专为Rust语言打造,正处于积极的实验与发展阶段。它的设计理念不同于现有的Rust文档工具,意味着你将体验到前所未有的文...

gitblog_00214的博客 951

Rust 注释与文档注释:代码即文档的工程实践

Rust的文档系统深度整合了代码与文档,通过rustdoc工具自动生成专业API文档。其特色包括:支持Markdown格式的文档注释(///),自动测试示例代码确保文档准确性,以及模块级(//!)和crate级文档。文档注释应包含标准部分如参数说明、返回值、示例等,而普通注释(//)则用于解释代码意图。Rust还支持文档内部链接和特殊标记,使文档更结构化。实践表明,完善的文档(如优先队列库示例)能显著提升代码可维护性,体现了Rust"代码即文档"的设计理念。

超哥的博客 960

2507rust,rust写驱动

2507rust,rust写驱动

个人进步之路 1248

【Rust 基础篇】Rust 文档注释

本篇博客详细介绍了在 Rust 中使用文档注释的方法、格式和最佳实践。文档注释是一种强大的工具,可以为代码提供详细的说明和示例,帮助其他开发人员理解和使用代码。希望本篇博客对你理解和应用 Rust 中的文档注释有所帮助。

繁依Fanyi的博客 1984

Unreal-Rust 技术文档

--- ## 安装指南 ### 前提条件 在开始集成 `Unreal-Rust` 到您的项目之前,请确保满足以下条件: - **Unreal Engine 5**:访问官方站点下载并安装最新版本的UE5。 - **Git LFS**:通过官方网站或命令行工具安装,并执行 `git lfs install` 初始化。 - **ue4cli**:使用Python的包管理器pip安装,运行 `p...

gitblog_01274的博客 1228

Rust 之四 文档规范、编码规范

编程语言除了有语言标准之外,还有一系列其他约定俗成的标准,例如,项目管理、文档规范、编码规范等等。很多早期的编程语言则没有一个统一的标准,而 Rust 编程语言作为一个完全开源的后起之秀,在诞生之初就针对性的解决完善了这些问题!

技术干货 1063

Rust 中的文档测试(Documentation Tests)

Rust 中的文档测试(Documentation Tests)

m0_62599305的博客 566
上一篇: 构建可扩展 Rust 项目:从模块化到 Workspace 工程化实践
下一篇: 手把手带你写 Rust 测试
Rust研习社
博客等级 码龄11年 52粉丝 84原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值