Tock OS 文档构建问题：Kernel 结构体文档缺失分析

问题现象

在 Tock OS 项目的文档构建过程中，出现了一个有趣的现象：当使用特定参数构建文档时，核心的 Kernel 结构体文档会神秘消失。具体表现为：

1. 在线文档中 Kernel 结构体没有显示文档内容，类型名称也不可点击
2. 本地使用标准 cargo doc 命令构建时文档显示正常
3. 问题仅在使用 -Z unstable-options --document-hidden-items 参数时出现

技术背景

在 Rust 生态中，cargo doc 是标准的文档生成工具，它基于 rustdoc 工作。文档生成过程中有几个关键参数会影响输出结果：

• --document-private-items：文档化所有项目，包括私有项
• -Z unstable-options --document-hidden-items：实验性功能，用于文档化被隐藏的项

问题根源

经过分析，这个问题揭示了 Rust 文档工具链中一个有趣的行为：

1. Kernel 结构体可能被标记为某种"隐藏"状态
2. 当启用 --document-hidden-items 时，rustdoc 可能采用了不同的处理逻辑
3. 这种处理逻辑意外地导致了对 Kernel 结构体文档的完全过滤

解决方案

项目维护者提出了一个合理的解决方案：改用 cargo doc --document-private-items 参数。这个方案的优势在于：

1. 它是一个稳定版的参数，不依赖实验性功能
2. 更符合项目实际需求（需要文档化私有项而非隐藏项）
3. 避免了不稳定参数可能带来的副作用

经验总结

这个案例为 Rust 项目文档构建提供了几点重要启示：

1. 实验性参数可能产生意想不到的副作用，应谨慎使用
2. 文档构建参数的选择需要根据实际需求仔细考量
3. 在线文档和本地文档的差异可能揭示构建配置问题
4. 对于核心结构体的文档缺失应该引起高度重视

最佳实践建议

对于类似项目，建议采用以下文档构建策略：

1. 优先使用稳定版参数
2. 在 CI 中验证在线文档的完整性
3. 对核心结构体添加文档测试（doc-test）
4. 定期比较本地构建和在线构建的结果差异

这个问题虽然表现形式简单，但揭示了 Rust 文档工具链中参数选择的重要性，也为其他项目提供了有价值的参考经验。