如何让cargo doc对二进制crate模块的公开函数缺失文档发出警告？

核心解决步骤 #

1. 在Crate根配置全局Lint规则 #

仅需在src/main.rs最顶部添加以下crate级属性，无需在每个模块重复添加：

#![warn(missing_docs)]

这个规则会触发所有**对外公开（pub修饰）**的项（模块、函数、结构体等）的缺失文档警告。

如果需要检查私有模块内的pub项（仅crate内部可见的公开项），额外添加：

#![warn(missing_docs_private_items)]

2. 确保模块和目标项的可见性 #

• 若要检查对外公开的模块及其中的函数，需在main.rs中公开导入模块：

  pub mod database;
  pub mod files;
  pub mod validate;
  

• 若仅检查内部模块的pub函数，保持普通导入mod database;即可，但需配合missing_docs_private_items规则。

3. 强制执行文档检查 #

运行以下命令生成文档并查看完整警告：

cargo doc --no-deps --warn-missing-docs

--no-deps跳过依赖的文档生成，--warn-missing-docs确保文档缺失检查被强制执行。

常见误区 #

• 不要在模块文件中添加#![warn(missing_docs)]：#!开头的属性是crate级配置，模块内添加会导致作用域错误，仅需在crate根（main.rs）配置一次。
• 私有模块内的pub项默认不会触发missing_docs警告，因为它们对crate外部不可见，需启用missing_docs_private_items规则才能检测这类项。

内容的提问来源于stack exchange，提问作者Fabio Matos