Faster doctests still need an explicit example contract
Rust’s March 2025 doctest repair enabled combined compilation. Keep that speed benefit while making exceptional example and isolation requirements explicit.
By 
Paul. Languages and frameworks
Faster documentation tests are valuable when the examples still prove what their readers think they prove. Rust's March 2025 repair to combined doctest compilation is a good reason to distinguish the compiler's packaging choices from the example's contract. Keep ordinary examples eligible for batching, and state exceptional isolation requirements explicitly. Disabling the improvement everywhere would make every example pay for a few unusual assumptions.
Looking back from November 2026, Rust 1.85.0 introduced the stable 2024 edition on 20 February 2025. The 1.85.1 announcement on 18 March explains that an implementation bug had caused combined doctests to fall back to the earlier unmerged approach. The point release repaired that behavior. This chronology matters: a patch release could make an intended edition behavior take effect even where earlier runs had appeared unchanged.
Compilation and execution are separate contracts
A doctest is a code example checked by rustdoc. Compiling examples separately repeats work. Combining compatible examples into one executable can reduce that compilation overhead. It does not follow that all examples now execute in one shared process, with one example's static variables contaminating the next.
The edition guide, consulted in November 2026, explicitly distinguishes these behaviors: compatible examples can share the compiled binary while still running in independent processes. Its current explanation supports the mechanism; it is not a dated March benchmark. The distinction prevents an unnecessary migration response built around a runtime-sharing problem that the change does not generally create.
Process separation also has limits that compilation batching cannot settle. Two independently running examples could still address the same external database or choose the same fixed file path. Those resources exist outside their separate memory spaces. A project relying on them needs its own resource ownership, regardless of how rustdoc packages the executable.
Consider an illustrative library manual containing ordinary arithmetic examples and one example about diagnostic locations. The arithmetic examples care about return values. The diagnostic example may care about its generated source position. Treating them as identical tests hides the unusual assumption in the second example and encourages a broad workaround when only one contract needs attention.
Make the exceptional example say why
The current guide describes automatic exclusions, including compile_fail examples, explicit edition tags and certain crate-level or global attributes. It also documents standalone_crate for examples that need separate compilation but cannot be identified automatically. Location-sensitive behavior and generated type paths deserve particular attention when reviewing failures after migration.
These are distinct reasons for separation. An example expected to fail compilation cannot be treated as an ordinary successful program. An example whose meaning depends on crate structure may require a separate crate even if its execution would otherwise be harmless. “Isolation” should identify the actual property needed, rather than act as a general label for every unexpected result.
Before adding an exception, decide whether the example is testing the public API or an incidental detail of the generated harness. If a diagnostic-location example promises an exact location as part of the documentation, preserving separate compilation may be justified. If an unrelated example merely compares an implementation-dependent type path, changing that assertion may better express its intended lesson.
That is a proposed editorial and engineering decision, not an assertion that any particular crate's examples were repaired here. No Rust build or performance experiment was run for this article. The release announcement establishes the historical repair; only a project's own evaluation could establish its local speed improvement and compatibility.
Keep the compiler and edition in the record
A compiler version and a language edition answer different questions. The installed toolchain determines available implementation behavior and fixes. The edition chooses a set of language and tooling conventions for the crate. Recording only one can make a doctest failure difficult to reproduce, especially around the point release that enabled the intended behavior.
For a proposed migration, retain the toolchain version, the crate edition and the failing example. Examine whether separate compilation changes the relevant outcome before applying a wider opt-out. Keep the exception near the example so the next maintainer can understand why it exists without searching an old incident discussion.
A successful example also needs a reader-facing check. Hidden setup can make a code block executable while concealing the very precondition that a user needs. Faster checks do not repair misleading documentation. Review whether the visible example explains necessary inputs and whether its assertion supports the claim beside it.
The business benefit is dependable feedback on the documentation people use to integrate a library. Shorter waiting may encourage frequent checks, but the article supplies no estimate of hours saved. A maintained example can prevent a misleading instruction from surviving a release; that value depends on the actual integration and cannot be inferred from a compiler announcement alone.
Separate compilation can remain the right choice
The strongest counterargument is simplicity. A small set of unusual examples may be easier to understand when each has a separate crate, and compilation overhead may not matter to that project. That can be a sound tradeoff when the reason is documented and the examples genuinely require the stronger boundary.
The limit is turning that local choice into a rule for every example. Ordinary snippets should not inherit an exceptional compilation requirement without a reason. Conversely, a speed target should not pressure an author into dropping an assertion that expresses a real public contract. Choose the check first, then the least costly execution arrangement that preserves it.
For custom software development, include documentation examples in the toolchain handover. Record the compiler and edition, keep necessary exceptions visible and separate compilation savings from runtime isolation claims. A useful migration leaves both a faster routine path and an understandable reason for each example that needs something different.