skip to content

A Rust library uses compile_fail doctests to prove misuse of its API is rejected; how do they differ from no_run, ignore and should_panic, and why are they fragile?

level: seniorimportance: should knowfreq 25%

answer

  1. pass on failure
  2. any error counts
  3. error codes are nightly-only
  4. keep a compiling twin

basics

~20 s

compile_fail passes when the block fails to compile; no_run compiles without running, ignore skips the block, and should_panic must compile and then panic. Any compile error satisfies compile_fail, a typo included, and stable rustdoc does not check an error code.

solid answer

~40 s

A `compile_fail` block inverts the doctest: it passes only if compilation fails, which lets a library show that misuse, such as asking for a `Level::default()` that does not exist, is rejected. `no_run` compiles but never runs, `ignore` builds nothing, and `should_panic` must compile and then panic. The guard is fragile because any error passes it: a misspelled path proves nothing. On stable, rustdoc 1.99.1 ran a `compile_fail,E0308` block whose real error was E0599 and passed it, since checking the code is nightly-only. A later release may also accept the code. So keep each guard to one misuse next to a compiling twin, and park guards on a `#[cfg(doctest)]` item to keep them out of the docs. Since 1.85 the 2024 edition merges doctests, but compiles `compile_fail` blocks alone.

code

rust · 22 lines
rust
/// A log severity. It has no `Default`: callers must choose a minimum.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Level {
    Info,
    Warn,
    Error,
}

/// The twin that must keep compiling:
///
/// ```
/// let min = logfilter::Level::Warn;
/// assert!(logfilter::Level::Error >= min);
/// ```
///
/// The guard: asking for a default level must not compile.
///
/// ```compile_fail
/// let min = logfilter::Level::default();
/// ```
#[cfg(doctest)]
pub struct LevelGuards;

go deeper

for a junior

Know the four attributes: no_run compiles only, ignore skips, should_panic expects a panic, compile_fail expects a compile error.

for a middle

Explain how each attribute changes what rustdoc compiles and runs, and why no_run beats ignore for valid code that should not execute.

for a senior

Use compile_fail guards with a compiling twin, a cfg(doctest) home and a reviewed error, knowing stable ignores error codes and new releases can flip a guard.

for a principal

Decide which API rules deserve compile-time guards in tests versus type-level design, and budget review of guards into toolchain upgrades.

## The code-block attributes A doc-comment code block can carry attributes after the opening fence, such as ```` ```no_run ````. They change how rustdoc builds the block and when it counts as passing: | Attribute | Compiled? | Run? | Passes when | |---|---|---|---| | none | yes | yes | it compiles and runs without panicking | | `no_run` | yes | no | it compiles | | `ignore` | no | no | never checked; reported as ignored | | `should_panic` | yes | yes | it compiles and then panics | | `compile_fail` | attempted | no | compilation fails | - **`no_run`** suits examples that would touch the network or a file the test machine lacks: the API usage is still type-checked. - **`ignore`** checks nothing, and the rustdoc book calls it almost never what you want. Prefer `text` for non-code, or hidden `#` lines to make a fragment compile. - **`should_panic`** documents a panic, for example `logfilter::parse("loud").unwrap()`. Choosing among them: - Valid code that is safe to run: no attribute. - Valid code that must not run in tests: `no_run`. - Code that demonstrates a documented panic: `should_panic`. - Code that must be rejected by the compiler: `compile_fail`. - A fragment that is not Rust at all: a `text` block rather than `ignore`. ## compile_fail as an API guard A library maintainer often wants to prove that something **cannot** be written. In the `logfilter` crate, `Level` deliberately has no `Default`, so callers must choose a minimum severity. A `compile_fail` block containing `let min = logfilter::Level::default();` passes today because rustc rejects it with E0599. If someone later adds `#[derive(Default)]`, the guard fails with `Test compiled successfully, but it's marked `compile_fail`.`, and the change has to be discussed. Guards are not documentation readers need, so they are often attached to an item that exists only while rustdoc collects tests: `#[cfg(doctest)] pub struct LevelGuards;`. The item, and its doc comment, never appear in the published API. ## Why compile_fail guards are fragile The attribute asserts only that **some** error occurred. Three things follow: 1. **Any error passes.** A block that misspells the path, `logfilter::Levl::Warn`, fails with E0433 and the guard reports `ok` while proving nothing about `Level`. A missing import or a renamed module does the same. 2. **Stable does not check error codes.** rustdoc on nightly can verify a code written as `compile_fail,E0599`. On stable it does not: rustdoc 1.99.1 ran a `compile_fail,E0308` block whose real error was E0599 and still reported it as passing. The rustdoc book calls the code check nightly-only and unlikely to be stabilised. 3. **The language grows.** The rustdoc book warns that code failing with the current release may compile in a future one, as features are added; then the guard fails although your API did not change. Ways to keep guards honest: - Write each guard as **one misuse** next to a **compiling twin** that differs by that one token, so a typo shows up in the twin. - When adding a guard, change it once to a plain block and read the real error with `cargo test --doc` (Cargo's command line covers the flags). - Review guards when bumping the toolchain, and prefer the type system's own errors over long, clever snippets. ## Doctests under the 2024 edition Since Rust 1.85, a crate on the **2024 edition** has its compatible doctests **merged** into one executable to save compile time; each still runs in its own process. Some blocks are never merged: - `compile_fail` blocks, and blocks with an edition tag; - blocks using global attributes such as `#[global_allocator]` or crate-wide `#![...]` attributes; - blocks that define a macro using `$crate`. The `standalone_crate` attribute forces a block to compile on its own. It matters for examples that depend on their position: on rustc 1.99.1, an example asserting `std::panic::Location::caller().line() == 3` passed on edition 2021 but saw line 27 when merged under 2024, and passed again with `standalone_crate`. Merging applies only when the whole crate is on 2024. The edition's other changes belong to the material on the 2024 edition.

  • How can a compile_fail guard pass for the wrong reason, and how do you catch it?
    Any compile error satisfies it, so a misspelled path or a missing import passes while proving nothing. Keep a compiling twin that differs by one token, and when writing the guard, turn it into a plain block once to read the real error. Stable rustdoc will not check a written error code for you.
  • What did the 2024 edition change for Rust doctests?
    Since 1.85, a 2024-edition crate's compatible doctests are merged into one executable, though each still runs in its own process. compile_fail blocks, edition-tagged blocks, crate-attribute blocks and $crate macros stay separate, and standalone_crate forces it. Examples reading Location or type_name can change result.
  • When should a Rust doc example be no_run rather than ignore?
    Almost always, when the code is valid but should not execute in tests, for example it reads a log file the machine lacks. no_run still compiles it, so API drift breaks the build; ignore checks nothing and silently rots. For non-Rust text, use a text block instead.

  • Writing compile_fail,E0599 makes stable rustdoc verify that E0599 is the error emitted.
  • An ignore block is still type-checked, it just is not executed.
  • A should_panic doctest passes if the example fails to compile.
  • Once a compile_fail guard passes, it keeps proving the same rule on every future release.
  • Guard doctests must sit on public items and show up in the published documentation.

Assumes Rust 1.99 on the 2024 edition; since 1.85 rustdoc merges compatible doctests in 2024-edition crates but always compiles compile_fail blocks alone.