How to document a binary Rust crate project?

Question

I have a program that I've written in Rust and I would like document it. I've looked on line and found:

• 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

I've added doc comments to the code:

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

The problem I'm having now is that after I run cargo doc, I get all the other documentation generated for all the crates my program uses, but the HTML documentation does not induce my program. I've been looking around and I haven't see anything that talks about just documenting a single program, usually I see material about documenting crates. If I can use Rust's documentation system for a stand alone program, how would can I do this?

Answer 1

The problem is that your function is private (which makes sense for a binary crate). However, rustdoc currently only documents public items by default (which makes sense for a library crate). You can use the flag --document-private-items to also include private functions and the like:

cargo doc --document-private-items

There is some discussion about this feature and the default we should be using here.

Furthermore, I recently opened a PR to change the default behavior for binary crates, so that private item for binary crates are documented by default. This change is expected to arrive on the stable compiler on January the 31st 2020 (1.41.0).