文档注释
/// 文档
文档注释 是 CoddyKit 上的免费 Learn Rust Coding 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Learn Rust Coding 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Learn Rust Coding 课程共包含 4 节课。
Rust 中的文档
Rust 将一流的文档功能内置于语言中。特殊注释会成为由 cargo doc 生成的 HTML 文档。
外部文档注释
使用 /// 为其后面的项编写文档，包括函数、结构体、枚举等。文本支持 Markdown。
/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}Markdown 格式
文档注释会渲染 Markdown：标题、列表、粗体和链接都可以使用。行内代码使用反引号，章节标题以 # 开头。
/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
width * height
}常见文档章节
约定俗成的标题可以让文档更易浏览：
# Examples— 使用示例# Panics— 发生恐慌的情况# Errors— 返回的错误# Safety— 不安全代码的不变量
内部文档注释
使用 //! 为包含它的项编写文档，通常是模块或整个 crate。将它放在文件顶部。
//! # My Math Crate
//!
//! Utilities for basic arithmetic.
pub fn double(n: i32) -> i32 {
n * 2
}记录结构体和字段
每个公共项（包括结构体字段）都可以拥有自己的文档注释。
/// A point in 2D space.
pub struct Point {
/// The horizontal coordinate.
pub x: f64,
/// The vertical coordinate.
pub y: f64,
}生成文档
cargo doc 会将 HTML 文档构建到 target/doc 中。添加 --open 可以在浏览器中查看文档。
cargo doc --open排除依赖
默认情况下，Cargo 也会为您的依赖生成文档。使用 --no-deps 仅为您的 crate 构建文档。
cargo doc --no-deps --open文档内链接
将其他项的路径写在方括号中即可创建链接。Rust 会解析该路径，并在生成的文档中创建可点击的链接。
/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
a - b
}为什么要编写文档
高质量的文档会带来许多好处：
- 自动生成可搜索的 HTML
- 发布 crate 后可免费发布到 docs.rs
- 文档中的示例会经过测试（文档测试）
- 帮助队友，也方便未来的您
记录模块
结合使用内部和外部注释：模块文件以描述模块的 //! 开头，内部每个项都使用 ///。
//! Geometry helpers.
/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
side * 4.0
}快速检查
哪种注释语法可以记录紧随其后的项？
回顾
您学习了文档注释：
///记录后面的项；//!记录包含它的项- 它们支持 Markdown 以及
# Examples等章节 - 文档内链接可以连接各个项
cargo doc --open生成并查看 HTML 文档
常见问题解答
「文档注释」课时是免费的吗？
是的 — 「文档注释」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Learn Rust Coding 课程的其余内容，请升级到 CoddyKit PRO。 Learn Rust Coding 课程共包含 4 节课。
「文档注释」这节课中我会学到什么？
/// 文档 你通过在浏览器中直接运行的动手代码来练习 Learn Rust Coding，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Learn Rust Coding 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Learn Rust Coding 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「文档注释」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Learn Rust Coding 课中编写并运行代码吗？
能。每节 Learn Rust Coding 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。