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.

The Campfire
CommentsThanks. Your comment is waiting for the desk. Once it is approved it appears here within about a minute.
Add a comment