rustrustdoc

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


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: enter image description here

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


Solution

  • 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.