Cargo doc does not generate documentation for private items in a project that is both a library and binary

Question

When I run cargo doc, it does not seem to generate documentation for the library in my project. I am using the latest version of Rust as answered by this post: How can I include private modules when generating documentation via Cargo?

This is my structure:

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

main.rs contains just the "main" function to start up:

use test_doc::Core;

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

lib.rs contains the actual logic:

mod services;

/// Core process
pub struct Core;

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

Then my_service.rs contains some more logic:

/// 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 inside my_service folder simply serves as an entry point:

pub mod my_service;

This code compiles and executes successfully, but I'm not sure why the docs are not generated properly.

Here is a screenshot of the docs that are generated when I run cargo doc --open:

I can't find MyService documented anywhere... (clicking "Structs" link just jumps to an anchor point on the main page)

Reread the post you linked: *Documentation **for binaries** includes private items from the binary crate by default.*. You are looking at the documentation for a library. What happens when you `cargo doc --document-private-items`? — Shepmaster, Aug 10 '21 at 14:03
Tried that, same thing. As I understood, it the linked posts is saying this should be default behaviour by Rust 1.41 — l3utterfly, Aug 10 '21 at 14:05
Yes, if you document a **binary** (main.rs). You are looking at the documentation for a **library** (lib.rs). — Shepmaster, Aug 10 '21 at 14:07
I'm a little confused. My project contains both `main.rs`, and `lib.rs`. So is it a library or a binary? Or both? — l3utterfly, Aug 10 '21 at 14:10
Incidentally, I tried `cargo doc --lib --open`, to generate the documentation for the library, it still doesn't work — l3utterfly, Aug 10 '21 at 14:10
It's both, but `cargo doc` evidently defaults to looking at the library. — Shepmaster, Aug 10 '21 at 14:12
From `cargo doc --help`, you can also use `cargo doc --bins` to document the binary (thus including private items). — L. F., Aug 10 '21 at 14:14

Shepmaster · Accepted Answer · 2021-08-10T14:41:37.573

3

A much smaller example:

src/main.rs

//! THE BINARY

fn main() {}

src/lib.rs

//! THE LIBRARY

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

When I run cargo doc, I see that Rust 1.55 on macOS generates the documentation for the library. As stated in How can I include private modules when generating documentation via Cargo?, when documenting a library, private items are not included. You need to pass the --document-private-items flag to see them.

If you wish to document the binary, you'll need to pass the --bin or --bins flag. If you wish to document the library, you'll need to pass the --lib flag.

edited Aug 10 '21 at 14:41

answered Aug 10 '21 at 14:18

Shepmaster

388,571
95
1,107
1,366

1

Doesn't `cargo doc` generate documentation for the *binary* by default? Because only after I added the `--lib` flag via `cargo doc --lib --open --document-private-items` I managed to generate docs for the library (including private items) – l3utterfly Aug 10 '21 at 14:21
@l3utterfly that's why I added the doc comments to each crate ("THE LIBRARY" / "THE BINARY"). Then it's easy to see which one it opens by default. For me, it was the library. See also [For a package where a library and a binary have the same name, have cargo doc ignore the bin](https://github.com/rust-lang/cargo/issues/4341#issuecomment-321667740). – Shepmaster Aug 10 '21 at 14:34
Hmm.. I have different behaviour, my cargo docs the "binary" by default. Probably a config in my cargo.toml file. Thanks – l3utterfly Aug 10 '21 at 14:38
@l3utterfly are you on Linux or Windows, by any chance? It may be something as silly as "order of files on disk". – Shepmaster Aug 10 '21 at 14:40
I am on windows. – l3utterfly Aug 10 '21 at 14:44

Cargo doc does not generate documentation for private items in a project that is both a library and binary

1 Answers1