2.1 有意义的文档注释

有意义的文档注释 — Comprehensive Rust

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/meaningful-doc-comments.html

2.1 有意义的文档注释

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
/// 客户端的 API // ❌ 缺乏细节
pub mod client {}

/// 从 A 到 B 的函数 // ❌ 冗余
fn a_to_b(a: A) -> B {...}
 
/// 连接到数据库。 // ❌ 缺乏细节
fn connect() -> Result<(), Error> {...}
  • 文档注释是开发者最常接触的文档形式。

  • 好的文档注释提供代码、名称与类型无法传达的信息,同时不重复那些显而易见的内容。


2.1.1 你在为谁写?

01-你在为谁写? — Comprehensive Rust

2.1.2 库文档 vs 应用文档

02-库文档 vs 应用文档 — Comprehensive Rust

2.1.3 文档注释的结构

03-文档注释的结构 — Comprehensive Rust

2.1.4 点名与指路

04-点名与指路 — Comprehensive Rust

2.1.5 避免冗余

05-避免冗余 — Comprehensive Rust

2.1.6 名称与签名不够

06-名称与签名不够 — Comprehensive Rust

2.1.7 写什么与为什么,而非怎么与哪里

07-写什么与为什么,而非怎么与哪里 — Comprehensive Rust

2.1.8 练习

08-练习 — Comprehensive Rust

最后修改 August 11, 2026: 更新 (70a5af133)