Cargo test interprets symbols from functions' documentation

[vkabadzhova]

Problem

When running the cargo test command, I receive some errors after the tests have already finished indicating success.

However, the indicated symbols (the "^") I have used nowhere but the code documentation. If I remove them, the problem disappears:

Steps

1. Put the "^" symbol from the English keyboard in a doc comment;
2. Run cargo t (tests that pass)

---

The function of question is located in a public struct which is in src/some-directory/file.rs

Possible Solution(s)

I tend to think it interprets those symbols wrongly, since I would be surprised if cargo t should anyhow intervene with the functions' documentation.

Notes

Note: cargo t works as expected in the following cases:

1. other symbols + "^" (for example the line:
   [3 spaces] /// new vector which [5 spaces] |^
2. the symbol in the start of the line
   [some spaces] ///[some spaces]^

But it fails in the following case:
///[14 spaces]^

Version

cargo 1.59.0 (49d8809dc 2022-02-10)
release: 1.59.0
commit-hash: 49d8809dc2d3e6e0d5ec634fcf26d8e2aab67130
commit-date: 2022-02-10
host: x86_64-unknown-linux-gnu
libgit2: 1.3.0 (sys:0.13.23 vendored)
libcurl: 7.80.0-DEV (sys:0.4.51+curl-7.80.0 vendored ssl:OpenSSL/1.1.1l)
os: Arch Linux [64-bit]

[ehuss]

This is normal behavior for documentation tests. When there is a code block in a doc comment, cargo test will run rustdoc which will try to compile all of those code blocks. In markdown, when something is indented, it is considered a code block. In this case, it is interpreting the ^ as the beginning of a rust expression, but it is not a valid one.

There are various ways to work around this. It looks like you are writing some diagrams. One approach is to mark that as a text block:

```text
can place anything here
```

I'm going to close in favor of these issues:
rust-lang/rust#88590
rust-lang/rust#64162
rust-lang/rust#63193

[weihanglo]

Thanks for the report. I believe it is an expected result. The content of a doc comment must also be a valid markdown. It will then be parsed by rustdoc to build HTML doc and run doctest. Since indented code blocks are also valid code blocks, they will then be run as doctests. That's why /// [4-space]^ leads to a compilation failure.

Here is another minimal example that also makes doctest fail.

/// Indentation with 4 spaces -> code block
///
///     1 + 1
pub fn test() {
    assert!(false);
}

To avoid this behavior, I recommend fencing your text with three backticks a.k.a. fenced code blocks, such like:

/// You doc comment
///
/// ```text
///          ^ ascii art
/// ```

[weihanglo]

Oops. A race condition with @ehuss 😆

[vkabadzhova]

Thank you @ehuss and @weihanglo for the answers.