不能忽略在文檔中編譯示例代碼的失敗

Question

我想爲我的Rust庫編寫示例代碼，但我不需要編譯示例代碼。

重現步驟：

1. cargo new

2. 一下添加到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

我得到一個錯誤：

$ 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。

Answer 1

您在Rust的文檔解析器中遇到了known issue。 Rust（Hoedown）使用的Markdown解析器似乎沒有正確識別圍欄代碼塊（三個反引號），除非它之前有空行。有some dispute這是否是期望的行爲或沒有，但無論哪種方式的問題，可以通過修改您的例子如下解決：

//! ## 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!"); 
} 

注意代碼塊之前領先//!線，這使得農村舞會成功識別代碼塊並適當地忽略它。