无法忽略文档中示例代码编译失败的问题。

Question

我正在尝试编写我的 Rust 库的示例代码，但我不需要样例代码被编译。

重现步骤：

1. cargo new

2. Add this to src/lib.rs

   //! ## How to use
   //! Validator usage:
   //! ```ignore
   //! fn validate(values: &Map) -> ValidateResults {
   //!    ValidateResults(vec!(
   //!        Validator::<String>::new(btreemap! {
   //!            "requiered".to_string() => true.to_json(),
   //!            "vtype".to_string() => "string".to_json(),
   //!        }).validate("title".to_string(), values.find(&["pages", "title"]$
   //!
   //!        Validator::<bool>::new(btreemap! {
   //!            "default".to_string() => false.to_json(),
   //!        }).validate("published".to_string(), values.find(&["published"])$
   //!    ))
   //! }
   //! ```
   pub fn main() {
       println!("Hello, world!");
   }
   

3. cargo test

I get an error:

$ cargo test
    Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/deps/sample-661c50cdfb6a999f

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

   Doc-tests sample

running 1 test
test _0 ... FAILED

failures:

---- _0 stdout ----
    error: expected one of `.`, `;`, `?`, `}`, or an operator, found `,`
 --> <anon>:4:69
  |
4 |    }).validate("published".to_string(), values.find(&["published"])),
  |                                                                     ^

error: macro undefined: 'btreemap!'
 --> <anon>:2:31
  |
2 |        Validator::<bool>::new(btreemap! {
  |                               ^^^^^^^^

error: aborting due to 2 previous errors

thread '_0' panicked at 'Box<Any>', ../src/librustc_errors/lib.rs:694
note: Run with `RUST_BACKTRACE=1` for a backtrace.
thread '_0' panicked at 'couldn't compile the test', ../src/librustdoc/test.rs:283


failures:
    _0

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

error: test failed

我如何忽略编译此示例代码时的错误？我使用的是 Rust 1.13.0 和 Cargo 0.13.0。

- mrLSD

---

Markdown的乐趣... - mcarton

Answer 1

你遇到了Rust文档解析器中的已知问题。Rust使用的Markdown解析器（Hoedown）似乎无法正确识别有栅栏代码块（三个反引号）除非在其前面有一个空行。关于这是否是期望的行为存在一些争议，但无论如何，问题都可以通过以下方式修正你的示例来解决：

//! ## How to use
//! Validator usage:
//!
//! ```ignore
//! fn validate(values: &Map) -> ValidateResults {
//!    ValidateResults(vec!(
//!        Validator::<String>::new(btreemap! {
//!            "requiered".to_string() => true.to_json(),
//!            "vtype".to_string() => "string".to_json(),
//!        }).validate("title".to_string(), values.find(&["pages", "title"]$
//!
//!        Validator::<bool>::new(btreemap! {
//!            "default".to_string() => false.to_json(),
//!        }).validate("published".to_string(), values.find(&["published"])$
//!    ))
//! }
//! ```
pub fn main() {
    println!("Hello, world!");
}

请注意代码块前面的//!行，在Hoedown中，这使得它能够成功识别代码块并适当地忽略它。

- Aurora0001