简介
能够运行的代码只是一个项目可以被他人安全维护的基础。一个适合交接的 Rust crate 还应使用一致的格式，避免可疑的代码模式，说明其公开接口，并确保测试持续通过。
在本实验中，你将使用 Rust 的标准项目工具修复一个小型库。你会依次使用 rustfmt、Clippy 和 rustdoc，然后将它们与测试套件结合，形成可重复的质量检查流程。代码规模很小，因此你可以专注于理解每个工具能够验证什么。
统一源代码格式
在此步骤中，你将使用 rustfmt 检测并修复代码布局差异，同时不改变程序行为。
进入准备好的库并打开源文件：
cd /home/labex/project/handoff-helpers
nano src/lib.rs
第一个函数是有效的 Rust 代码，但它的空格和缩进与文件的其他部分不一致。格式规则是机械性的，使用工具统一处理比让每位贡献者手动调整更加可靠。不要编辑文件，直接按 Ctrl+X 退出。
先使用检查模式：
cargo fmt -- --check
此命令预计会失败并显示差异。cargo fmt 会选择该软件包中的 Rust 文件。第一个 -- 表示 Cargo 选项结束，第二个 --check 会传递给 rustfmt。检查模式会报告差异，但不会重写文件，因此适合用于自动化检查。
现在应用格式化工具：
cargo fmt
再次打开源文件：
nano src/lib.rs
现在，第一个函数的空格、换行和缩进已经统一。函数名称和逻辑没有改变。退出 nano，然后确认检查模式不再产生输出：
cargo fmt -- --check
没有输出且命令成功退出，表示每个 Rust 文件都已经符合 rustfmt 的规则。
修复 Clippy 警告
在此步骤中，你将使用 Clippy 查找能够编译、但可以更清晰地表达意图的代码。
Rust 编译器会检查代码是否有效且类型安全。Clippy 会针对可疑、不必要地复杂或不符合 Rust 惯用写法的代码模式提供 lint 检查。使用将警告视为错误的方式运行它：
cargo clippy -- -D warnings
第一次运行预计会失败。与 rustfmt 一样，-- 会将后面的选项传递给底层工具。-D warnings 表示拒绝警告，因此在修复所有报告的警告之前，质量检查会以非零状态退出。
Clippy 指出了两项明确的改进：使用直接判断为空的方法，而不是将长度与零进行比较；同时接受切片，而不是要求调用者必须拥有一个 Vec。打开源文件：
nano src/lib.rs
将：
if cleaned.len() == 0 {
改为：
if cleaned.is_empty() {
然后将 open_count 的参数从：
tasks: &Vec<bool>
改为：
tasks: &[bool]
is_empty() 直接表达了要判断的问题。切片可以接受借用的序列数据，不会不必要地要求使用具体的向量容器。保存并退出 nano，然后格式化这次小修改并重新运行 Clippy：
cargo fmt
cargo clippy -- -D warnings
最后输出一行 Finished 且没有警告，说明该库已经在更严格的 lint 策略下成功编译。
编写公开接口文档
在此步骤中，你将添加文档注释并生成可浏览的 API 文档。
以 /// 开头的注释会说明其紧接着的项目。以 //! 开头的注释会说明所包含的 crate 或模块。Rustdoc 会将这两种注释转换为带链接的 HTML 文档。
打开库的源文件：
nano src/lib.rs
在文件最顶部添加以下两行：
//! Small helpers for preparing task data for reports.
#![deny(missing_docs)]
这个内部属性会将公开项目缺少文档的问题变成构建错误。它把文档要求从建议变成了明确的项目策略。
在 normalize_title 的正上方添加以下注释：
/// Returns a trimmed title, or `Untitled` when the input is blank.
在 open_count 的正上方添加以下注释：
/// Counts entries whose completion value is `false`.
保存并退出 nano。仅为这个软件包生成文档：
cargo doc --no-deps
cargo doc 会运行 rustdoc。--no-deps 选项会跳过依赖 crate 的文档生成，使结果更集中，生成速度也更快。生成的入口页面是 target/doc/handoff_helpers/index.html；Cargo 会将 Rust crate 名称中的连字符转换为下划线。
ls target/doc/handoff_helpers/index.html
如果能看到该路径，就说明 rustdoc 已生成 crate 页面，并且缺少文档的策略检查已经通过。
运行完整的质量检查流程
在此步骤中，你将把各个工具组合成一套可预测的交接前检查流程。
格式化、代码检查、文档生成和测试分别回答不同的问题：
- rustfmt 检查源代码是否采用标准布局；
- Clippy 检查是否仍存在已知的可疑或不清晰代码模式；
- 测试检查要求的行为是否仍然有效；
- rustdoc 检查是否能够根据项目策略为公开接口生成文档。
分别运行每项检查，这样失败时就能明确定位到某个环节。先检查格式：
cargo fmt -- --check
运行严格的 lint 检查：
cargo clippy -- -D warnings
运行库测试：
cargo test
输出应报告两个测试通过。最后，重新生成针对该软件包的文档：
cargo doc --no-deps
当这四条命令按此顺序全部成功时，说明该 crate 的格式统一、lint 检查通过、行为已通过测试，并且文档完整。在交接前重复运行这套流程，可以用可重复的证据证明质量，而不是只在最后凭目测判断。
总结
你使用 rustfmt 修复了代码格式，解决了严格的 Clippy 检查问题，为公开库接口编写了文档，生成了 rustdoc 输出，并确保测试持续通过。更重要的是，你将这些工具组合成了一套可重复的质量检查流程，为可靠的项目交接提供支持。
