The purpose of a documentation example extends beyond merely demonstrating
syntax. A reader can typically be expected to understand the mechanics of
calling a function or instantiating a struct. A truly valuable example
illustrates *why* and in *what context* an item should be used.[^1] It should
tell a small story or solve a miniature problem that illuminates the item's
purpose. For instance, an example for `String::clone()` should not just show
`hello.clone();`, but should demonstrate
a scenario where ownership rules necessitate creating a copy.[^1]

To achieve this, examples must be clear and concise. Any code that is not
directly relevant to the point being made—such as complex setup, boilerplate,
or unrelated logic—should be hidden to avoid distracting the reader.[^2]

### 2.3 Ergonomic Error Handling: Taming the `?` Operator

One of the most common ergonomic hurdles in writing doctests involves handling
functions that return a `Result`. The question mark (`?`) operator is the
idiomatic way to propagate errors in Rust, but it presents a challenge for
doctests. The implicit `fn main()` wrapper generated by `rustdoc` has a return
type of `()`, while the `?` operator can only be used in a function that
returns a `Result` or `Option`. This mismatch leads to a compilation error.[^2]

## Footnotes

[^1]: Duplicate example footnote
 [^2]: Another footnote
 [^3]: Not a footnote
 [^4]: Rustdoc doctests need fixing — Swatinem, accessed on 15 July 2025, <https://swatinem.de/blog/fix-rustdoc/>
