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