Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Why does a comment without fences trigger a doctest? [duplicate]

Tags:

rust

I have the following commented code in a crate:

/// Complex Expression
///
///     - The `Undefined` variant is used as a placeholder during code 
///       transformations. It must never occur in the final result.
pub enum Cexp {
    Undefined,
    Unimplemented,
}

When running cargo test on the crate it triggers a doctest run, which fails to compile. (In the playground make sure to run TEST rather than BUILD.)

   Doc-tests playground

running 1 test
test src/lib.rs - Cexp (line 3) ... FAILED

failures:

---- src/lib.rs - Cexp (line 3) stdout ----
error: unknown start of token: `
 --> src/lib.rs:4:7
  |
1 | - The `Undefined` variant is used as a placeholder during code 
  |       ^

The actual error message is of no concern. The rust compiler chokes on the comment text, which is no surprise. But why does this comment trigger a doctest run? According to the documentation doctests are supposed to be fenced with ```, which is not the case here.

like image 760
MB-F Avatar asked Jul 23 '19 07:07

MB-F


1 Answers

This behavior is actually explained in the documentation. In the very bottom it says (emphasis mine):

Rustdoc also accepts indented code blocks as an alternative to fenced code blocks: instead of surrounding your code with three backticks, you can indent each line by four or more spaces.

...

However, it's preferable to use fenced code blocks over indented code blocks. Not only are fenced code blocks considered more idiomatic for Rust code, but there is no way to use directives such as ignore or should_panic with indented code blocks.

like image 120
MB-F Avatar answered Oct 02 '22 14:10

MB-F