liveBook · Manning

Doc example

As explained in Idiomatic Rust

A doc example is executable code embedded in documentation to illustrate how an API or library is used.

A doc example embeds executable Rust code in API documentation so usage stays visible, compilable, and aligned with the implementation. section 6.11.2

A Rust doc example provides several practical benefits:

  • Runs as an integration-style documentation test when cargo test executes rustdoc examples. section 6.11.2
  • Lets examples omit main because rustdoc wraps the code for execution. section 6.11.2

LinkedList usage

```rust use linkedlist::LinkedList; let mut animals = LinkedList::new(); animals.append("chicken"); animals.append("ostrich"); animals.append("antelope"); ```

How Idiomatic Rust covers it

How deep it goes
Explains embedding, rustdoc preprocessing, and cargo test execution, but stops short of broader documentation design.
Examples
Demonstrates a LinkedList with animal values and shows successful Doc-tests output from cargo test.
What it assumes
Assumes a Rust library and basic Cargo workflow while teaching that rustdoc supplies the example's main function.
What you can do after
Apply it via rustdoc and cargo test to write executable API examples without manually adding main.
How it connects
Connects API design, rustdoc, integration testing, cargo test, and library documentation.
Cover of Idiomatic Rust
liveBookmanning.com
Read Idiomatic Rust on liveBook Get the book at manning.com

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.