Documentation test triggered without ```

[benhansen-io]

If you'd like to fix this bug, here's how!

---

The follow documentation comment is considered a documentation test. All of the Rust references I have read indicate ``` are needed to indicate a documentation test.

lib.rs

///                   
///     a             
/// b                 
pub fn some_lib_fn() {
                  
} 

Then running cargo test gives the following output:

 running 0 tests                                                                   
                                                                                   
 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out        
                                                                                   
    Doc-tests reproduce-doc-test                                                   
                                                                                   
 running 1 test                                                                    
 test src/lib.rs - some_lib_fn (line 1) ... FAILED                                 
                                                                                   
 failures:                                                                         
                                                                                   
 ---- src/lib.rs - some_lib_fn (line 1) stdout ----                                
         error[E0425]: cannot find value `a` in this scope                         
  --> src/lib.rs:2:1                                                               
   |                                                                               
 3 | a                                                                             
   | ^ not found in this scope                                                     
                                                                                   
 thread 'rustc' panicked at 'couldn't compile the test', librustdoc/test.rs:298:13 
 note: Run with `RUST_BACKTRACE=1` for a backtrace.                                
                                                                                   
                                                                                   
 failures:                                                                         
     src/lib.rs - some_lib_fn (line 1)                                             
                                                                                   
 test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out    
                                                                                   
 error: test failed, to rerun pass '--doc'                                         

[sfackler]

Markdown code blocks are indicated by ``` or leading whitespace: http://spec.commonmark.org/0.28/#indented-code-blocks

[benhansen-io]

Thanks for the response. That's reasonable. It might be good to document this behavior at https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html. It wasn't obvious to me that indented blocks are supposed to be treated as executable tests as opposed to generic code includes.

It also seems inconsistent that the following are not considered tests:

///               
///     a         
///               
pub fn some_fn() {
                  
}

///               
///     a         
pub fn some_fn() {
}

[steveklabnik]

Marking as t-doc; this just falls out of the markdown rules, but probably worth calling out anyway.

[steveklabnik]

I'm happy to mentor anyone who wants to fix this bug! Here's how:

Modify the start of https://github.com/rust-lang/rust/blob/master/src/doc/rustdoc/src/documentation-tests.md to mention that the triple backticks is the most common way of writing a block of code, but Markdown also supports indenting four times.

I'm happy to answer any additional questions!

[ogham]

I’d like to take this on!

@steveklabnik, do you think it’s worth linking to the CommonMark spec (linked above), or would that be out of scope for an introduction to doctests?

[steveklabnik]

I think that'd be great; in fact, we should probably link to it in general when talking about documentation, that's extra credit though :)

[ogham]

I had a go at writing it in #51158. I thought adding a new section to the end would be better than adding another example at the start, to keep the introduction focussed.