Cargo doc不能为既是库又是二进制的项目生成私有项文档。

Question

当我运行命令时，它似乎没有为我的项目库生成文档。我正在使用最新版本的Rust，如此帖子所回答的：如何在通过Cargo生成文档时包含私有模块？ 这是我的目录结构：

- services/
    - mod.rs
    - my_service.rs
- lib.rs
- main.rs

main.rs 中只包含启动程序的 "main" 函数：

use test_doc::Core;

fn main() {
    Core::start();
}

lib.rs 包含实际的逻辑：

mod services;

/// Core process
pub struct Core;

impl Core {
    pub fn start() -> ! {
        loop {
            // do stuff here    
        }
    }
}

接下来，my_service.rs 包含了一些更多的逻辑：

/// My service should do stuff
pub struct MyService;

impl MyService {
    /// This function actually does stuff
    pub fn do_stuff(&self) -> &'static str {
        "doing stuff"
    }
}

mod.rs在my_service文件夹内仅用作入口点：

pub mod my_service;

这段代码可以编译并成功运行，但我不确定为什么文档未能正确生成。这是我运行时生成的文档截图：。我无法在任何地方找到MyService的文档...... （点击“Structs”链接只会跳转到主页面上的锚点）。

- l3utterfly

---

如果您记录一个二进制文件（main.rs），那么您正在查看一个库（lib.rs）的文档。 - Shepmaster

我有点困惑。我的项目包含main.rs和lib.rs两个文件。那么它是一个库还是一个二进制文件？或者两者都是？ - l3utterfly

顺便提一下，我尝试了 cargo doc --lib --open 命令来生成库的文档，但它仍然无法正常工作。 - l3utterfly

运行命令 cargo doc --lib --open --document-private-items，生成文档并打开私有项的文档。 - Shepmaster

它是两者兼备的，但是“cargo doc”显然默认查看库。 - Shepmaster

Answer 1

一个更小的例子： src/main.rs

//! THE BINARY

fn main() {}

src/lib.rs

//! THE LIBRARY

/// You can't see me
fn private() {}

当我运行 cargo doc 命令时，我发现在 macOS 上的 Rust 1.55 会生成库的文档。如How can I include private modules when generating documentation via Cargo?中所述，在为库生成文档时，私有项将不会包含在内。你需要传递 --document-private-items 标志才能看到它们。

如果你想要文档化可执行文件，你需要传递 --bin 或 --bins 标志。如果你想要文档化库，你需要传递 --lib 标志。

- Shepmaster

---

默认情况下，cargo doc 生成的是二进制文件的文档吗？只有通过 cargo doc --lib --open --document-private-items 添加 --lib 标志后，我才能生成库（包括私有项）的文档。 - l3utterfly

@l3utterfly 这就是为什么我在每个板条箱（“库”/“二进制文件”）中添加了文档注释的原因。然后很容易看出它默认打开哪一个。对我来说，是库。另请参见对于包含同名库和二进制文件的软件包，请让cargo doc忽略bin。 - Shepmaster

嗯...我的行为不同，我的货物文档默认情况下是“二进制”的。可能是我cargo.toml文件中的配置问题。谢谢。 - l3utterfly

@l3utterfly 你是在 Linux 还是 Windows 上工作呢？可能只是“磁盘上文件的顺序”这样的小问题。 - Shepmaster

我正在使用Windows。 - l3utterfly