如何故意编写不完整/失败的文档？

Question

我知道 Rust 的主要功能之一是内置文档测试。您可以像这样编写任何评论，它将在生成的文档中可用。但是如何创建不完整/无法运行的注释呢？

    /// ## Foo Function 
    /// Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    /// Duis eleifend at dolor auctor maximus. Vestibulum 
    /// ### How to use
    /// ```
    /// use my_app::Item; // how to skip testing this part ?
    /// Item::map_from_doc(&foo) <---- this error on test since I do not declare `foo` 
    /// ```
    pub fn foo_func(doc: &str) -> Result<Self, ItemError> {...}

我不想为foo变量编写整个代码。我只是想给用户一个关于功能使用的简单解释。我认为应该有一种方法可以跳过这部分的文档测试。

到目前为止我只能找到关于隐藏部分代码的信息，这意味着我需要编写完整的示例代码并隐藏其中的一些代码。https://doc.rust-lang.org/rustdoc/documentation-tests.html

如何故意编写不完整/失败的文档？

Answer 1

您链接的页面下方是“属性”部分，其中记录了可用于配置非标准/“异常”行为的各种指令：

/// ```ignore
/// fn foo() {
/// ```

该ignore指令告诉 Rust 忽略你的代码。这几乎不是您想要的，因为它是最通用的。相反，text如果它不是代码，请考虑使用 s 对其进行注释，或者使用#s 来获取仅显示您关心的部分的工作示例。

我不会复制整个部分，您可以阅读它，但其中列出的其他有用值包括：

• should_panic告诉 rustdoc 代码应该正确编译，但实际上不能作为测试通过。
• 该no_run属性将编译您的代码，但不会运行它。这对于诸如“以下是如何检索网页”之类的示例非常重要，您希望确保这些示例能够编译，但可能会在没有网络访问权限的测试环境中运行。
• compile_fail告诉 rustdoc 编译应该失败。如果编译成功，则测试将失败。
• edition2018告诉 rustdoc 代码示例应该使用 2018 版 Rust 进行编译。同样，您可以指定edition2015使用2015版编译代码。

就您而言，ignore可能是最好的属性。从技术上讲，您可以使用，但您实际上并没有尝试演示或断言编译失败，因此对我来说compile_fail感觉像是过度规范。