# 命名与文档

提炼自指南的 Naming 与 When and how to write documentation 章节。

## 命名

### 方法命名

遵循 Rust 标准库的方法命名风格。`as_…()` / `to_…()` / `into_…()` 等前缀要与相应的 `self` 参数约定匹配（借用 / 复制 / 消耗）。对应 clippy `wrong_self_convention`；另见 Comprehensive Rust 的[命名约定](https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions.html)。

### 生命周期命名

- 生命周期用描述性名称，类型生命周期尤其如此。
- 例外：极端泛型的抽象（如 `Cow`）；能用匿名生命周期 `'_` 的地方就用；表达方法输入与输出关系、或局部 higher-ranked 约束（`for<'a>`）时可用单字符——此类最多两个，再多强烈建议改用描述性名称。

### 泛型参数命名

用与所代表事物相关的短名（单字符或多字符）。单字母可以，但字母应暗示类型，理想取自最重要的 trait bound。无约束场景用 `T`、`U` 即可（如 `Vec<T>`）。

### 扩展 trait 命名

以 `Ext` 结尾（原文记法 `~Ext` 后缀），如 `ForeignTypeExt`。

### 初始化/构造函数命名

- 构造器：`new()`；多于一个时用 `new_with_foo()`；返回 `Result` 时用 `try_new()`。
- 值到值转换：`from_foo()`，并配对关联的 `From` 实现（何时应实现 `From` 见[官方文档](https://doc.rust-lang.org/std/convert/trait.From.html#when-to-implement-from)）。

### 避免缩写

不使用项目外的人不认识的缩写（尤其首字母缩写）；不用删字母式缩写。

例外：Wikipedia 上的常见缩写；项目外不会混淆的缩写（如 `IpAddr`）——由作者与 reviewer 判断，倾向仍然是不缩写。

## 文档注释

### 公开 API 必须有文档

可用 `missing_docs` lint 辅助。最佳实践：

- 覆盖示例：不必每个函数都有示例，但应在某处提供足够示例覆盖 crate 的主要功能，让人了解用法。
- 可能因畸形输入 panic 的函数，必须文档化 panic 条件。
- unsafe 函数与 trait：清晰文档化不变量（invariants）。
- 使用大写开头和标点。
- 不解释语言基础。反面示例：给 `MockFileSystem` 写 "A mock implementation of the FileSystem trait, intended to be used in unit tests."。
- 不简单复述：`/// Removes an element.` 配 `remove_element()` 不如不写（这种情况可 allow lint）。
- 枚举变体的文档可省略，名字自解释时尤其如此。

### 格式

- `///` 文档化紧随其后的条目：函数、struct、enum、trait、类型别名。
- `//!` 文档化模块或库本身，放文件顶部。
- 遵循官方 Rust 风格指南对 doc comment 的要求；用 Markdown。
- `//` 用于实现注释、用户不关心的 TODO、注释掉的代码等非文档内容。
- 直接写 `///` / `//!`，不要用宏生成文档——让文档在源码中直接可读。
- 鼓励文档注释与实现注释混用，各说各的：

```rust
/// Finds the first `FooItem` with the given `name`, or `None` if not present.
// TODO: crbug.com/12345 - `name` should be &str, not String.
pub fn get_named(items: &[FooItem], name: String) -> Option<&FooItem> { … }
```