cargo doc and cargo test erroneosly detect a documentation test

[r-bk]

Problem

The following code snippet causes cargo test to fail.

pub mod m1 {
    /** This const

    has a multiline document string.
    */
    pub const GOOD_DOC: u32 = 1;

    pub mod m2 {
        /** This const

        has a multiline document string.
        */
        pub const BAD_DOC: u32 = 0;
    }
}

The failure is as follows:

running 1 test
test src/lib.rs - m1::m2::BAD_DOC (line 11) ... FAILED

failures:

---- src/lib.rs - m1::m2::BAD_DOC (line 11) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `a`
 --> src/lib.rs:12:5
  |
3 | has a multiline document string.
  |     ^ expected one of 8 possible tokens

error: aborting due to 1 previous error

Couldn't compile the test.

failures:
    src/lib.rs - m1::m2::BAD_DOC (line 11)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.03s

error: doctest failed, to rerun pass `--doc`

Moreover, cargo doc generates the documentation of BAD_DOC constant as if it contained a code snippet
.

Interestingly, the GOOD_DOC constant is treated correctly both in cargo doc and cargo test, i.e., no doc-test is created for it and documentation is generated without a code snippet.

This behavior is strange because the doc string is exactly the same in both constants. The only difference is that BAD_DOC is nested in another module m2.

The expected behavior is to treat BAD_DOC the same way as GOOD_DOC:

• there should be no doc-test generated and cargo test shouldn't fail
• cargo doc shouldn't generate a code snippet

Steps

No response

Possible Solution(s)

No response

Notes

No response

Version

cargo 1.77.1 (e52e36006 2024-03-26)
release: 1.77.1
commit-hash: e52e360061cacbbeac79f7f1215a7a90b6f08442
commit-date: 2024-03-26
host: x86_64-unknown-linux-gnu
libgit2: 1.7.2 (sys:0.18.2 vendored)
libcurl: 8.5.0-DEV (sys:0.4.70+curl-8.5.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 2023
os: Ubuntu 23.10 (mantic) [64-bit]

[epage]

See also

pub mod m1 {
    /** This const

    has a multiline document string.
    */
    pub const GOOD_DOC: u32 = 1;

    pub mod m2 {
        /** This const

        has a multiline document string.
        */
        pub const BAD_DOC: u32 = 0;
    }

    pub mod m3 {
        /** This const
         *
         * has a multiline document string.
         */
        pub const GOOD_DOC: u32 = 0;
    }
}

Note that m3::GOOD_DOC uses * prefixes on the lines and it works.

Likely whats happening is that * is needed to establish the indent level. Without that, the raw indentation is passed along to the markdown parser and it is being treated as an indented code block.

However, I'm unsure how m1::GOOD_DOC isn't treated as an indented code block.

Moving this over for the rustdoc team to triage in case the inconsistency between m1::GOOD_DOC and m2::BAD_DOC is unexpected.

[ehuss]

Thanks for the report! This is a known issue where:

• That style of doc comment is converted to This const\n\n has a multiline document string.\n, where via the commonmark standard, the second section is an indented block
• Indendented blocks are treated as code blocks.
• rustdoc defaults all codeblocks to be treated as rust.

Closing as a duplicate of #59867, #64162, #88590, and #100225.