Error with doctest, but there are no test

Hello, I just added some documentation to a struct and now I have some error when running cargo test

The struct with the documentation is available here:

Any idea what cause the error?

rustdoc interprets comment lines surrounded by three backticks as well as ones indented by four or more spaces as code blocks:

/// code block with backticks
/// ```
/// let x = 4;
/// ```

/// code block with indentation
///    let x = 5;

By default, such code blocks are considered documentation tests and cargo test will compile and run the code contained within to ensure that examples keep working and such.

In your case, you can mark it as text like so

/// ```text
///          -----       -----
///         |  Z  |     |  Z  |
///         o --- o --- o --- o --- o ---
///         |  X  |  Z  |  X  |  Z  |  X |
///     --- o --- o --- o --- o --- o ---
///    | X  |  Z  |  X  |  Z  |  X  |
///     --- o --- o --- o --- o --- o ---
///         |  X  |  Z  |  X  |  Z  |  X |
///     --- o --- o --- o --- o --- o ---
///    | X  |  Z  |  X  |  Z  |  X  |
///     --- o --- o --- o --- o --- o
///               |  Z  |     |  Z  |
///                -----       -----
/// ```
3 Likes

Indenting a block by four or more spaces creates a code block in Markdown, and code blocks in doc comments are assumed to be Rust code by default and run as doctests, so it's trying to compile your ASCII art :slight_smile:

If you want it to be treated as text you can put:

```text
anything inside this block is rendered like a code block but not interpreted as Rust code
```
1 Like

Ohh, I didn't know that indentation also trigger a codeblock. Thank you :slight_smile:

error: expected expression, found `}`
 --> src/lib.rs:18:1
  |
8 | } _doctest_main_src_lib_rs_12_0() }
  | ^ expected expression

error: aborting due to previous error

Couldn't compile the test.

Ouch, quite an unuseful error. Technically it does contain the information that the doctest is generated from src/lib.rs:12:0, but it's certainly not immediately clear what's going on.

I think this only happens because of the unfortunate coincidence that your diagram is almost syntactically valid Rust code, except for ending in a series of prefix - operators. If we replace the o intersections with + we see instead an error of

error: expected expression, found `+`
 --> src/lib.rs:15:5
  |
5 |     + --- + --- + --- + --- + ---
  |     ^ expected expression

error: aborting due to previous error

Couldn't compile the test.

Is there any open issue tracking improving this further? A potential solution could be rustdoc generating a procedural macro along the lines of documentation_test!("path/to/src/lib.rs", 12:0..25:0), such that spans can work out... though this requires new proc macro API to get a spanned TokenStream back from the real source file to avoid regressing normal errors.

1 Like