2.1 有意义的文档注释 on 编程那些事儿

2.1.1 你在为谁写？

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.1 你在为谁写？

同事、合作者、大多沉默的 API 用户，还是仅仅你自己？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// 专家写给专家
/// Canonicalizes the MIR for the borrow checker. 
/// 
/// This pass ensures that all borrows conform to the NLL-Polonius constraints 
/// before we proceed to MIR-to-LLVM-IR translation. 
pub fn canonicalize_mir(mir: &mut Mir) {
 // ...
}

// 专家写给新手
/// Prepares the Mid-level IR (MIR) for borrow checking. 
/// 
/// The borrow checker operates on a simplified, "canonical" form of the MIR. 
/// This function performs that transformation. It is a prerequisite for the 
/// final stages of code generation. 
/// 
/// For more about Rust's intermediate representations, see the 
/// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html). 
pub fn canonicalize_mir(mir: &mut Mir) {
 // ...
}

背景：知识的诅咒（curse of knowledge）是一种认知偏差——专家会假定他人具备同等水平的专业知识与视角。

2.1.2 库文档 vs 应用文档

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.2 库文档 vs 应用文档

你可能见过基础 API 上详尽的文档——反复复述名称与类型签名。稳定且高度可复用的代码能负担得起这种投入，并获得正向投资回报（RoI）。

2.1.3 文档注释的结构

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.3 文档注释的结构

简短的一句话摘要。
更详细的说明。
特殊小节：代码示例、panic、错误、安全前置条件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
/// Parses a key-value pair from a string.
///
/// The input string must be in the format `key=value`. Everything before the
/// first '=' is treated as the key, and everything after is the value.
///
/// # Examples
///
/// ```
/// use my_crate::parse_key_value;
/// let (key, value) = parse_key_value("lang=rust").unwrap();
/// assert_eq!(key, "lang");
/// assert_eq!(value, "rust");
/// ```
///
/// # Panics
///
/// Panics if the input is empty.
///
/// # Errors
///
/// Returns a `ParseError::Malformed` if the string does not contain `=`.
///
/// # Safety
///
/// Triggers undefined behavior if...
unsafe fn parse_key_value(s: &str) -> Result<(String, String), ParseError>

enum ParseError {
 Empty,
 Malformed,
}

地道的 Rust 文档注释遵循约定结构，便于开发者阅读。

2.1.4 点名与指路

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.4 点名与指路

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
/// A parsed representation of a [MARC 21 record leader][leader].
///
/// A MARC leader contains metadata that dictates how to interpret the rest 
/// of the record.
///
/// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html
pub struct Leader {
 /// Determines the schema and the set of valid subsequent data fields. 
 ///
 /// Encoded in byte 6 of the leader. 
 pub type_of_record: char,

 /// Indicates whether to parse relationship fields, such as a "773 Host 
 /// Item Entry" for an article within a larger work. 
 /// 
 /// Encoded in byte 7 of the leader. 
 pub bibliographic_level: char,
 // ... 其他字段
}

/// Parses the [leader of a MARC 21 record][leader].
/// 
/// The leader is encoded as a fixed-length 24-byte field, containing metadata 
/// that determines the semantic interpretation of the rest of the record. 
/// 
/// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html
pub fn parse_leader(leader_bytes: &[u8; 24]) -> Result<Leader, MarcError> {
 todo!()
}

#[derive(Debug)]
pub enum MarcError {}

动机：文档读者不会像读心爱小说里的对话那样仔细读你的大多数文档注释。

2.1.5 避免冗余

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.5 避免冗余

名称与类型签名已传达大量信息，不要在注释里再重复一遍！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// 重复了名称/类型信息。可省略！
/// Parses an ipv4 from a str. Returns an option for failure modes.
fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }

// 重复了字段名已显而易见的信息。可省略！
struct BusinessAsset {
 /// The customer id.
 customer_id: u64,
}

// 一上来就提类型名，别这样！
/// `ServerSynchronizer` is an orchestrator that sends local edits [...]
struct ServerSynchronizer { ... }

// 更好！聚焦于目的。
/// Sends local edits [...]
struct ServerSynchronizer { ... }

// 一上来就提函数名，别这样！
/// `sync_to_server` sends local edits [...]
fn sync_to_server(...)

// 更好！聚焦于函数本身。
/// Sends local edits [...]
fn sync_to_server(...)

动机：仅仅复述名称/签名信息的文档，对 API 用户毫无新意。

2.1.6 名称与签名不够

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.6 名称与签名不够

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// 不好
/// Returns a future that resolves when operation completes. 
fn sync_to_server() -> Future<Bool>;

// 好
/// Sends local edits to the server, overwriting concurrent edits 
/// if any happened. 
fn sync_to_server() -> Future<Bool>;

// 不好
/// Returns an error if sending the email fails. 
fn send(&self, email: Email) -> Result<(), Error>;

// 好
/// Queues the email for background delivery and returns immediately. 
///
/// Returns an error immediately if the email is malformed. 
fn send(&self, email: Email) -> Result<(), Error>;

动机：API 设计者可能过度相信“函数名与签名就够当文档”。

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

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

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

避免记录可能频繁变更的无关细节。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// 不好
/// Saves a `User` record to the Postgres database. 
/// 
/// This function opens a new connection and begins a transaction. It checks 
/// if a user with the given ID exists with a `SELECT` query. If a user is 
/// not found, performs an `INSERT`. 
/// 
/// # Errors 
/// 
/// Returns an error if any database operation fails. 
pub fn save_user(user: &User) -> Result<(), db::Error> {
 // ...
}

// 好
/// Atomically saves a user record. 
/// 
/// # Errors 
/// 
/// Returns a `db::Error::DuplicateUsername` error if the user (keyed by 
/// `user.username` field) already exists. 
pub fn save_user(user: &User) -> Result<(), db::Error> {
 // ...
}

动机：用户想知道 API 契约（对该函数保证什么），而非实现细节。

2.1.8 练习

Tue, 11 Aug 2026 11:30:00 +0800

译文 · 基于 Comprehensive Rust

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

2.1.8 练习

不必要的细节有时可能暗示着真正需要文档化的东西。

1
2
3
4


// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
/// Sorts a slice. Implemented using recursive quicksort.
fn sort_quickly<T: Ord>(to_sort: &mut [T]) { ... }

问问学员：这个注释对该函数是否必要？