nightly: unexpected "could not parse code block" in indented block docs in presence of backticks

[vthriller]

I believe this is a minimal example. Warning disappears if either:

• backticks are removed
• indentation is removed
• ///-style formatting is used

// don't even need to be in `impl`, yeah
//pub struct Foo {}
//impl Foo {
    /**
    Does nothing, returns `()`

    yadda-yadda-yadda
    */
    pub fn foo() {}
//}

$ cargo doc
 Documenting rust-nightly-doc-wat v0.1.0 (/home/thriller/tmp/rust-nightly-doc-wat)
    Finished dev [unoptimized + debuginfo] target(s) in 1.08s
$ cargo +nightly doc
 Documenting rust-nightly-doc-wat v0.1.0 (/home/thriller/tmp/rust-nightly-doc-wat)
warning: could not parse code block as Rust code
 --> src/lib.rs:5:5
  |
5 | /     Does nothing, returns `()`
6 | |
7 | |     yadda-yadda-yadda
  | |_____________________^
  |
  = note: error from rustc: unknown start of token: `

    Finished dev [unoptimized + debuginfo] target(s) in 1.29s

$ rustc +nightly --version --verbose
rustc 1.34.0-nightly (e54494727 2019-02-13)
binary: rustc
commit-hash: e54494727855cd14229f5d456591ed2a2f027c46
commit-date: 2019-02-13
host: x86_64-unknown-linux-gnu
release: 1.34.0-nightly
LLVM version: 8.0

(straight from rustup)

[vthriller]

Oh, and the HTML render is fine, no unexpected code blocks or anything crazy:

[GuillaumeGomez]

You should see backticks in rendered docs. However, the issue is on your side. You have to add a backslash before them. :) Try this out and tell us if it's still an issue.

[vthriller]

Wait, what? I don't get your reply at all. In case you missed it, I'm not complaining about how docstring is rendered, I only added screenshot to show that not all parts of rustdoc try to see markdown-indented-code-blocks where there are none; the issue is with the warning that makes no sense.

[LukasKalbertodt]

I get these warnings when compiling the boolinator crate (for example, for this doc comment). Full output:

warning: could not parse code block as Rust code
  --> src/lib.rs:52:5
   |
52 |     If this value is `true`, returns `Some(())`; `None` otherwise.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:57:5
   |
57 |     If this value is `true`, returns `Some(some)`; `None` otherwise.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:62:5
   |
62 |     If this value is `true`, returns `Some(some())`; `None` otherwise. 
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:68:5
   |
68 |     If this value is `true`, returns `opt`; `None` otherwise. 
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:73:5
   |
73 |     If this value is `true`, returns `opt()`; `None` otherwise. 
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:79:5
   |
79 |     If this value is `true`, returns `Ok(ok)`; `Err(err)` otherwise. 
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:84:5
   |
84 |     If this value is `true`, returns `Ok(ok())`; `Err(err())` otherwise. 
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:90:5
   |
90 |     If this value is `true`, returns `Ok(())`; `Err(err)` otherwise.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
  --> src/lib.rs:95:5
   |
95 |     If this value is `true`, returns `Ok(())`; `Err(err())` otherwise.
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: error from rustc: unknown start of token: `

warning: could not parse code block as Rust code
   --> src/lib.rs:101:5
    |
101 |     If this value is `true`, does nothing; panics with `msg` otherwise.
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = note: error from rustc: unknown start of token: 

I very much doubt that this is intended.

Warning occurs with:

• rustc 1.33.0-nightly (7bac68a 2019-01-21)
• rustc 1.34.0-nightly (146aa60 2019-02-18)

No warnings with rustc 1.33.0-nightly (0c0c585 2019-01-19). So the problem is in these commits. Thus, the PR causing these warnings is probably #56884. CC @euclio

[euclio]

Yeah, the pass to check codeblock syntax is probably missing handling for the extra margin introduced by comments in that style. Shouldn't be too hard to fix.

In the meantime, you can work around this by writing your comments with /// or like so:

/**
 * If this value is `true`, returns `Some(())`; `None` otherwise.
 */