documentation - 如何在文档测试中忽略一行？

Question

如何在文档代码中写入一行但让编译器忽略它？

我想写

/// # Examples
///
/// To clone something, do
///
/// ```
/// IGNORE_FOR_COMPILATION_BUT_SHOW: let cloned = myValue.clone();
/// # let cloned = 5.clone();
/// ```

我想得到：

例子

要克隆某些东西，请执行

let cloned = myValue.clone();

---

但编译器仍应编译示例（克隆 5）。

编辑：我也希望 cargo 运行示例，但省略一行。

Answer 1

文档说你可以这样做：

/// ```rust,ignore
/// highlighted as rust code but ignored by rustdoc
/// ```

还有rust,no_run一个编译但不运行示例代码。

或者，您可以使用与普通代码相同的解决方案：将其注释掉。

/// ```rust
/// let x=5;
/// // x = 6;  // won't be run
/// assert_eq!(x, 5);
/// ```

Answer 2

如果你想忽略 doctests 中的一部分 Rust 代码，你可能需要阅读运行文档测试部分。基本上将该代码提取到不同的块中并将该块设置为rust,ignore.

这将完全忽略IGNORE_FOR_COMPILATION_BUT_SHOW，但其余的将运行：

///```rust,ignore
///IGNORE_FOR_COMPILATION_BUT_SHOW: let cloned = myValue.clone(); 
///```

///```rust
/// # let cloned = 5.clone();
/// ```

如果您希望 rustdoc 编译您的文档测试，但不运行它，您可以使用rust,no_run