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 
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
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
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.