如何记录一个二进制 Rust crate 项目？

Question

我有一个使用Rust编写的程序，我想为它撰写文档。我在网上查找了相关信息，找到了以下链接：

• https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html
• https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text

我已经在代码中添加了文档注释。

/// This is a documented function
fn example() {
    println!("Hi there");
}

我现在遇到的问题是，运行后，我会得到所有程序使用的板条箱的其他文档生成，但HTML文档没有包含我的程序。我一直在寻找相关资料，但我没有看到任何关于仅记录单个程序的内容，通常我看到的都是有关记录板条箱的材料。如果我可以使用Rust的文档系统来独立编写程序，我该如何做呢？

- 9716278

---

据我所知，cargo doc只会文档化公共函数。你的示例函数是公共的并且可以从根目录 (main.rs 或 lib.rs) 访问吗？ - SCappella

Answer 1

问题在于你的函数是私有的（对于二进制包来说这是有意义的）。然而，rustdoc 默认情况下只会记录公共项（对于库包来说这是有意义的）。你可以使用标志 --document-private-items 来包括私有函数等内容：

cargo doc --document-private-items

关于这个功能以及我们应该使用的默认设置 在这里 有一些讨论。

此外，我最近开了一个 PR 来更改二进制 crate 的默认行为，使得二进制 crate 的私有项默认被记录。这个变化预计将在2020年1月31日（1.41.0）的稳定编译器中到来。

- Lukas Kalbertodt