liveBook · Manning

Cargo doc

As explained in Idiomatic Rust

cargo doc is Cargo's command for generating documentation for a Rust package and its dependencies.

cargo doc generates HTML documentation for a Rust crate, making its public API easier to inspect and use. The output appears in target/doc, with the crate index as its landing page. section 6.11.2

Use cargo doc to:

  • Inspect public structs and methods, even before adding explicit documentation. section 6.11.2
  • Evaluate API design through names, crate-level descriptions, method explanations, and usage examples. section 6.11.2
  • Regenerate documentation continuously with cargo watch -x doc while editing. section 6.11.2

Documenting a linked-list crate

Run cargo doc, then open target/doc/linkedlist/index.html. Add //! comments to src/lib.rs for crate-level guidance and /// comments before LinkedList and its methods. Regenerate the documentation to see the landing page and API descriptions become more useful. section 6.11.2

How Idiomatic Rust covers it

How deep it goes
Generates HTML and explains documentation comments, but stops short of documenting advanced configuration.
Examples
Uses a linkedlist crate, LinkedList API pages, crate-level examples, and target/doc output.
What it assumes
Assumes a Rust crate with source code and public items, while demonstrating documentation comments from zero.
What you can do after
Operate Cargo to generate documentation, inspect public APIs, and regenerate pages during editing.
How it connects
Connects rustdoc, Rust documentation comments, crate APIs, and API design.
Cover of Idiomatic Rust
liveBookmanning.com
Read Idiomatic Rust on liveBook Get the book at manning.com

Also explained in

Compare how 2 books explain cargo doc →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Idiomatic Rust. The section links point to the parts of the book it draws on.