A Compile-Fail Example Can Pass for the Wrong Error

A voice application might expose a SafeTranscript type whose private field prevents callers from constructing one before a review step. Its documentation can show the forbidden construction with a Rust compile_fail code block. That looks like a test of the safety boundary. It is only a test that the entire example fails to compile.

The rustdoc documentation test guide says a compile_fail example succeeds when compilation fails and fails when compilation succeeds. It does not require a particular diagnostic. Imagine this documentation beside a public tuple struct with a private field:

/// ```compile_fail
/// let raw = String::from("unreviewed speech");
/// let item = speech_api::SafeTranscript(raw);
/// ```
pub struct SafeTranscript(String);

The intended error is that external callers cannot use the private tuple constructor. If the crate is actually named voice_api, however, the unresolved speech_api path also makes the doctest pass. A reader sees an example apparently proving the constructor is restricted, while the test never reached that constructor. A missing import, misspelled method, or syntax error can create the same false confidence.

Rustdoc also transforms examples before compilation: it may inject a crate import, add common lint allowances, and wrap code without main in a function. Lines prefixed with # can provide hidden setup that still compiles. Those conveniences make short examples useful, but they make it especially important to inspect the diagnostic when a negative example first lands or after an API rename.

One practical pattern is to place a normal compiling example nearby that imports the same public type and shows the permitted review path. That catches a broken path in the positive example, though it cannot prove the negative example failed for the intended reason. For a restriction whose exact failure matters, add a separate compiler-facing test that checks the expected diagnostic. Rustdoc’s nightly-only error-number annotation can check that a specified error code appears, but the same fence is treated as plain text on stable, and the annotation does not assert that no other errors occurred.

Use compile_fail to teach the boundary and catch accidental acceptance. Check the compiler output, plus a working public-API example, before treating the doctest as evidence of why the boundary holds.