Distinguish between fenced and indented code blocks in error message

[lightclient]

EDIT: It turns out that the issue I was facing was caused by my doc comment being interpreted as a code block, based on the indented code block rule in markdown.

--

Summary

The following doc comment fails to compile using cargo test --doc:

///
///    \
///x

Example repository here.

Error Output

> cargo test --doc
Finished dev [unoptimized + debuginfo] target(s) in 0.00s
Doc-tests weird

running 1 test
test src/lib.rs - main (line 2) ... FAILED

failures:

---- src/lib.rs - main (line 2) stdout ----
error: unknown start of token: \
 --> src/lib.rs:3:1
  |
3 | \
  | ^

error: aborting due to previous error

Couldn't compile the test.

failures:
    src/lib.rs - main (line 2)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

error: test failed, to rerun pass '--doc'

What I've Tried

I've found a few things (I'm sure this is not an exhaustive list to describe the problem):

• There must be an empty line above the backslash
• There must be a non-empty line below the backslash
• There must be at least 4 spaces between the backslash and the doc comment ///

Expected

The snippet compiles without issue.

Meta

I've verified the issue is present using 1.37.0 on both x86_64-apple-darwin and x86_64-unknown-linux-gnu.

[estebank]

The four leading chars start a markdown code block. The error is the same as having a .rs file whose only contents are a backslash.

[lightclient]

@estebank is this the expected behavior? I can't find it documented anywhere.

[estebank]

It is. It is equivalent to writing

```
\
```

Which is the prevalent style in the echosystem, but you can also write it

    \

like you did here. These code blocks get identified as rust code and get compiled and run as tests.

[ehuss]

I don't think it is clearly documented as such, but indented content is a code block per the markdown spec, and here it is documented that code blocks default to the Rust language, and are tested by default.

[lightclient]

If I replace my above example with:

///    \

It compiles successfully, which seems to contradict the markdown specification @ehuss pointed to. Am I missing something more?

[ehuss]

I believe that is caused by the unindent pass which detects the indentation level and removes it.

[lightclient]

Cool, thanks for clearing this up for me @ehuss & @estebank.

Please close this if you feel like no clarifications to the documentation should be made. I'd be happy to submit a PR if, however, that would be a helpful addition.

[ehuss]

It does occasionally trip people up. I think there are a few things that could be done:

• rustdoc: module flag to prevent code blocks without a lang item from counting as rust #59867 — Provide a way to turn it off.
• Provide a better error message. This would probably need enhancements to pulldown-cmark to distinguish between fenced and indented code blocks.

This is also mentioned in syntax reference. I'm not sure if repeating it in the docs will really help, since I doubt most people will thoroughly read the entire rustdoc manual (and remember everything).

But I think it's up to the rustdoc team if they want more documentation, or changing the error message.

[estebank]

I do think it would be interesting to extend parser errors emitted by rustdoc to have a note similar to "errors found while parsing code block in doc string". The interaction of indented code blocks and unindent is non-obvious and I would guess not entirely intended.

[GuillaumeGomez]

I do think it would be interesting to extend parser errors emitted by rustdoc to have a note similar to "errors found while parsing code block in doc string". The interaction of indented code blocks and unindent is non-obvious and I would guess not entirely intended.

I agree, it's been already a few times that people are having issues with this.