Doc Tests
Tested examples.
Doc Tests is a free Learn Rust Coding lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Learn Rust Coding learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Are Doc Tests?
Doc tests are code examples inside doc comments that Cargo actually compiles and runs. They keep your documentation correct and your examples working.
Code in Doc Comments
Put example code in a fenced code block (three backticks) inside a /// comment, under an # Examples heading. The default language is Rust.
/// Doubles a number.
///
/// # Examples
///
/// let result = my_crate::double(4);
/// assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
n * 2
}Running Doc Tests
Doc tests run as part of cargo test. They are reported separately under a Doc-tests section.
cargo testAssertions in Examples
Examples usually include assertions so a wrong example fails the test, not just compiles.
/// Returns the larger of two values.
///
/// # Examples
///
/// assert_eq!(my_crate::max(3, 7), 7);
/// assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
if a > b { a } else { b }
}Hiding Setup Lines
Prefix a line with # to run it but hide it from the rendered docs. Useful for boilerplate like imports.
/// # Examples
///
/// # use my_crate::Counter;
/// let mut c = Counter::new();
/// c.increment();
/// assert_eq!(c.value(), 1);Examples Using the Question Mark
To use the ? operator, wrap the body in a hidden main (or helper) that returns Result. Hidden lines start with #.
/// # Examples
///
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let n: i32 = "42".parse()?;
/// assert_eq!(n, 42);
/// # Ok(())
/// # }no_run Examples
Mark a fenced block with the no_run annotation to compile it but not execute it — handy for examples that need network or files.
/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
format!("contents of {url}")
}ignore and should_panic
Other annotations on the code fence:
ignore— neither compile nor runshould_panic— expected to paniccompile_fail— expected not to compile
Why Doc Tests Matter
Doc tests give you two wins at once:
- Documentation that is always accurate
- Free test coverage of your public examples
If an example breaks, the test suite fails.
Crate Name in Examples
Doc tests run as if from outside the crate, so reference items via the crate name (e.g. my_crate::func) or a use import.
Fenced vs Indented Blocks
Doc tests accept two block styles:
- A fenced block using three backticks, which allows annotations like
no_run - An indented block (four spaces), shown in these examples
Fenced blocks are more common in real code.
Quick Check
What does a line starting with # inside a doc-test code block do?
Recap
You learned doc tests:
- Code in
///blocks is compiled and run bycargo test - Use assertions to verify behavior
#hides setup lines from rendered docs- Annotations:
no_run,ignore,should_panic,compile_fail - They keep examples correct automatically
Frequently asked questions
Is the “Doc Tests” lesson free?
Yes — the full text of “Doc Tests” is free to read here on the web, and the Learn Rust Coding course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Learn Rust Coding course, upgrade to CoddyKit PRO.
What will I learn in “Doc Tests”?
Tested examples. You practise Learn Rust Coding with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Learn Rust Coding?
No prior experience is required. Learn Rust Coding on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Doc Tests” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Learn Rust Coding lesson?
Yes. Every Learn Rust Coding lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.