cargo doc: Turn Code Comments into a Website
cargo doc turns your Rust doc comments into a searchable HTML website for your crate and its dependencies. Use it to generate a local API reference or explore a dependency's API.
Why it exists
In a system with strong conventions like Rust, a standardized way to document code is critical. cargo doc solves the problem of generating, viewing, and sharing consistent API documentation directly from the source code, eliminating the need for separate tools and ensuring docs stay in sync with the code they describe.
The mental model
Think of cargo doc as a static site generator for your code's API. It reads the special /// and //! comments in your .rs files, understands their Markdown formatting, and compiles them into an interconnected set of HTML files. The result is a local version of what you see on docs.rs, complete with search, type linking, and source code viewing.
How it works
When you run cargo doc, Cargo invokes the rustdoc compiler tool. rustdoc analyzes your crate and, by default, its dependencies. It parses doc comments, renders Markdown, and cross-links types and modules. The final HTML, CSS, and JavaScript files are placed in the target/doc directory. The --open flag simply tells Cargo to open the root index.html file in your default web browser after the build succeeds.
When to use it
Use cargo doc constantly during development to check how your public API documentation will look. It's essential for library authors. Use it to explore the API of a new dependency locally by running it inside the dependency's cloned source directory. Use it with feature flags (--features "..." or --all-features) to see how the API changes with different configurations.
When not to use it
cargo doc is for API reference documentation, not for long-form guides or tutorials. While you can write extensive module-level documentation, a separate tool like mdBook is better for narrative content. Don't rely on it as a definitive test of what is public; a tool like cargo-public-api is better for that, as cargo doc can be configured to show private items.
One canonical example
To build and view the documentation for your current library crate, including all its public dependencies, and have it open automatically in your browser, run: cargo doc --open. To document only your library, excluding dependencies for a faster build, run: cargo doc --lib --no-deps. If you've made changes and want a clean build, first run cargo clean --doc and then your cargo doc command.
Interview question
For which task is cargo doc generally considered less suitable compared to other tools?
- a.Viewing documentation for a dependency's API locally.
- b.Previewing public API documentation during development.
- c.Generating an API reference website for a Rust crate.
- d.Creating extensive narrative guides or tutorials.Correct
Why? this is the answer
cargo doc is designed for API reference documentation generated directly from code comments. The card explicitly states it is not for long-form guides or tutorials, suggesting tools like mdBook for such content. The other options describe core use cases for cargo doc.
Just read this? Test yourself on what you have been reading.
Read the original → doc.rust-lang.org
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on rust — each one lists the topics its interview covers.
See open roles