Adding empty line in doc test causes it to fail

[andrewdavidmackenzie]

Problem
I have a doc comment/test like this:

/// An implementation runs with an array of inputs and returns a value (or null) and a
/// bool indicating if it should be ran again.
///
/// Any 'implementation' of a function must implement this trait
///
/// Example implementation of this trait:
///
/// extern crate core;
/// extern crate flow_impl;
/// extern crate flow_impl_derive;
/// #[macro_use]
/// extern crate serde_json;
///
/// use flow_impl::implementation::{Implementation, RUN_AGAIN, RunAgain};
/// use flow_impl_derive::FlowImpl;
/// use serde_json::Value;
///
/// #[derive(FlowImpl)]
/// pub struct Compare;
///
/// /*
///     A compare operator that takes two numbers and outputs the comparisons between them
/// */
/// impl Implementation for Compare {
///     fn run(&self, mut inputs: Vec<Vec<Value>>) -> (Option<Value>, RunAgain) {
///         let left = inputs[0].remove(0).as_i64().unwrap();
///         let right = inputs[1].remove(0).as_i64().unwrap();
///         let output = json!({
///                     "equal" : left == right,
///                     "lt" : left < right,
///                     "gt" : left > right,
///                     "lte" : left <= right,
///                     "gte" : left >= right
///                 });
///         (None, RUN_AGAIN)
///     }
/// }
///
/// # fn main() {
/// # }s

when I run cargo test --all all tests pass fine.

When I add a blank line before the json! line to give this:

/// An implementation runs with an array of inputs and returns a value (or null) and a
/// bool indicating if it should be ran again.
///
/// Any 'implementation' of a function must implement this trait
///
/// Example implementation of this trait:
///
/// extern crate core;
/// extern crate flow_impl;
/// extern crate flow_impl_derive;
/// #[macro_use]
/// extern crate serde_json;
///
/// use flow_impl::implementation::{Implementation, RUN_AGAIN, RunAgain};
/// use flow_impl_derive::FlowImpl;
/// use serde_json::Value;
///
/// #[derive(FlowImpl)]
/// pub struct Compare;
///
/// /*
///     A compare operator that takes two numbers and outputs the comparisons between them
/// */
/// impl Implementation for Compare {
///     fn run(&self, mut inputs: Vec<Vec<Value>>) -> (Option<Value>, RunAgain) {
///         let left = inputs[0].remove(0).as_i64().unwrap();
///         let right = inputs[1].remove(0).as_i64().unwrap();
///
///         let output = json!({
///                     "equal" : left == right,
///                     "lt" : left < right,
///                     "gt" : left > right,
///                     "lte" : left <= right,
///                     "gte" : left >= right
///                 });
///         (None, RUN_AGAIN)
///     }
/// }
///
/// # fn main() {
/// # }

the doc test then fails:

   Doc-tests flow_impl

running 1 test
test src/implementation.rs - implementation::Implementation (line 37) ... FAILED

failures:

---- src/implementation.rs - implementation::Implementation (line 37) stdout ----
error: unexpected close delimiter: `}`
  --> src/implementation.rs:47:1
   |
12 | }
   | ^ unexpected close delimiter

error: aborting due to previous error

Couldn't compile the test.

failures:
    src/implementation.rs - implementation::Implementation (line 37)

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

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

Took me quite a while to track down the cause. Maybe some complicated interac tions between a custom derive macro, serde_json macro or otherwise?

[ehuss]

I think this is expected. I don't see a code fence in your example, all the text up to the indented section is just regular text. Indented blocks are treated as rust code, so it is passing a partial snippet to rustc which will fail.

You probably want to wrap the whole thing with triple backticks.

For more information: rustdoc code blocks

cc rust-lang/rust#64162 where indentation causes confusion.

[andrewdavidmackenzie]

Ouch!!
That was dumb.... doesn't even match my other examples.
Sorry for wasting your time.